@live-change/frontend-template 0.9.198 → 0.9.200

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

@@ -0,0 +1,260 @@
+---
+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.
+
+## Auto-added fields from relations
+
+Relations automatically add **identifier fields** and **indexes** to the model. Do **not** re-declare these in `properties`.
+
+**Naming convention:** field name = parent model name with first letter lowercased (`Device` → `device`, `CostInvoice` → `costInvoice`).
+
+| Relation | Field(s) auto-added | Index(es) auto-added |
+|---|---|---|
+| `itemOf: { what: Device }` | `device` | `byDevice` |
+| `propertyOf: { what: Device }` | `device` | `byDevice` |
+| `userItem` | `user` | `byUser` |
+| `userProperty` | `user` | `byUser` |
+| `sessionOrUserProperty` | `sessionOrUserType`, `sessionOrUser` | `bySessionOrUser` (hash) |
+| `sessionOrUserProperty: { extendedWith: ['object'] }` | + `objectType`, `object` | composite indexes |
+| `propertyOfAny: { to: ['owner'] }` | `ownerType`, `owner` | `byOwner` (hash) |
+| `boundTo: { what: Device }` | `device` | `byDevice` (hash) |
+
+For multi-parent relations (e.g. `propertyOf: [{ what: A }, { what: B }]`), all index combinations are created (`byA`, `byB`, `byAAndB`).
+
+```js
+// ✅ Correct — only define YOUR fields
+definition.model({
+  name: 'Connection',
+  properties: {
+    status: { type: String }  // 'device' is NOT here — auto-added by itemOf
+  },
+  itemOf: { what: Device }   // adds 'device' field + 'byDevice' index
+})
+
+// ❌ Wrong — redundant field
+definition.model({
+  name: 'Connection',
+  properties: {
+    device: { type: String },  // ❌ already added by itemOf
+    status: { type: String }
+  },
+  itemOf: { what: Device }
+})
+```
+
+Use `node server/start.js describe --service myService --model MyModel --output yaml` to see all fields including auto-added ones.
+
+## 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.
+
+## `entity` models – granting access on creation
+
+Models with `entity` and `writeAccessControl` / `readAccessControl` check roles on every CRUD operation, but do **not** auto-grant roles to the creator. You must add a change trigger to grant the creator `'owner'` (or other roles) 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
+    if (!client?.user) return
+
+    await triggerService({ service: 'accessControl', type: 'accessControl_setAccess' }, {
+      objectType: 'myService_MyModel',
+      object,
+      roles: ['owner'],
+      sessionOrUserType: 'user_User',
+      sessionOrUser: client.user,
+      lastUpdate: new Date()
+    })
+  }
+})
+```
+
+Without this trigger, the creator cannot read or modify their own object. The `objectType` format is `serviceName_ModelName`.
+

package/.claude/rules/live-change-frontend-vue-primevue.md

@@ -0,0 +1,317 @@
+---
+description: Rules for Vue 3, PrimeVue, Tailwind frontend development on LiveChange
+globs: **/front/src/**/*.{vue,js,ts}
+---
+
+# Frontend on live-change-stack – Vue 3 + PrimeVue + Tailwind (Claude Code)
+
+Use these rules when working on frontends that talk to LiveChange backends.
+
+## Stack
+
+- Vue 3 + TypeScript
+- PrimeVue 4 for UI components
+- Tailwind CSS for styling (prefer utility classes, avoid unnecessary custom CSS)
+- vite-plugin-pages for file-based routing in `src/pages/`
+- `@live-change/vue3-ssr` for integration with the backend
+
+## Data loading – `live` + `Promise.all` (Suspense)
+
+- **Do not** use `ref(null)` + `onMounted` to fetch data.
+- Always fetch data using `await Promise.all([...])` and `live(path()...)` in `script setup`.
+- The root app should wrap pages with `<Suspense>` (usually handled by `ViewRoot` in live-change frontends).
+
+Example:
+
+```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 }))
+])
+```
+
+In templates, use the `.value` of these refs:
+
+```vue
+<template>
+  <div v-if="device.value">
+    {{ device.value.name }}
+  </div>
+</template>
+```
+
+## Commands and forms – choosing the right pattern
+
+There are 4 ways to execute backend actions. Use the right one:
+
+| Pattern | When to use |
+|---|---|
+| `editorData` | **Editing model records** (create/update). Drafts, validation, `AutoField`. Use for settings, editors, profiles. |
+| `actionData` | **One-shot action forms** (not CRUD). Submit once → done. Use for publish, invite, import. |
+| `api.command` | **Single button or programmatic calls** (no form fields). Use for delete, toggle, code-triggered actions. |
+| `<command-form>` | **Avoid.** Legacy, only for trivial prototypes. Prefer `editorData` or `actionData`. |
+
+Decision flow:
+
+1. Does the user fill in form fields? → **No**: use `api.command` (wrap in `workingZone.addPromise` for buttons).
+2. Is it editing a model record (create/update)? → **Yes**: use `editorData`. **No**: use `actionData`.
+3. Only use `<command-form>` for the simplest throwaway cases.
+
+## Form validation feedback
+
+Every field in a form using `editorData` or `actionData` **must** show validation errors. Never use bare `InputText`, `Dropdown`, or other PrimeVue inputs without error feedback.
+
+Three approaches (pick whichever fits the layout):
+
+1. **AutoField without slot** — auto-picks input and shows errors. Simplest, use by default.
+2. **AutoField with slot** — wrap a custom input inside `<AutoField>`. Still renders label + error automatically.
+3. **Manual `Message`** — add `<Message v-if="editor.propertiesErrors?.field" severity="error" variant="simple" size="small">` below the input. Use when AutoField wrapper doesn't fit.
+
+Always pass `:error="editor.propertiesErrors?.fieldName"` (or `formData.propertiesErrors?.fieldName` for `actionData`).
+
+## Form element requirement
+
+Forms using `editorData` or `actionData` with `EditorButtons` or `ActionButtons` **must** be wrapped in a `<form>` element with submit/reset handlers:
+
+```vue
+<!-- editorData -->
+<form @submit.prevent="editor.save()" @reset.prevent="editor.reset()">
+
+<!-- actionData -->
+<form @submit.prevent="formData.submit()" @reset.prevent="formData.reset()">
+```
+
+`EditorButtons` and `ActionButtons` use `type="submit"` / `type="reset"` on their internal buttons. Without a `<form>` parent, these buttons do nothing.
+
+### `api.command`
+
+```js
+await api.command(['deviceManager', 'createMyUserDevice'], {
+  name: 'My device'
+})
+
+await api.command(['deviceManager', 'deleteMyUserDevice'], {
+  device: id
+})
+```
+
+Format:
+
+- `['serviceName', 'actionName']` as the first argument,
+- payload object as the second argument.
+
+## Routing – `<route>` block and `meta.signedIn`
+
+- Each page in `src/pages/` can declare its route meta in a `<route>` block.
+- Use `meta.signedIn` for pages that require authentication.
+
+```vue
+<route>
+  { "name": "devices", "meta": { "signedIn": true } }
+</route>
+```
+
+Dynamic routes:
+
+- `[id].vue` corresponds to `/devices/:id`.
+
+```js
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+const deviceId = route.params.id
+```
+
+## Confirm + Toast for destructive actions
+
+```js
+import { useConfirm } from 'primevue/useconfirm'
+import { useToast } from 'primevue/usetoast'
+
+const confirm = useConfirm()
+const toast = useToast()
+
+function deleteDevice(id) {
+  confirm.require({
+    message: 'Are you sure you want to delete this device?',
+    header: 'Confirmation',
+    icon: 'pi pi-exclamation-triangle',
+    accept: async () => {
+      await api.command(['deviceManager', 'deleteMyUserDevice'], { device: id })
+      toast.add({
+        severity: 'success',
+        summary: 'Deleted',
+        life: 2000
+      })
+    }
+  })
+}
+```
+
+## Common UI patterns – list and detail
+
+### List page
+
+```vue
+<template>
+  <div class="container mx-auto p-4">
+    <div class="flex items-center justify-between mb-6">
+      <h1 class="text-2xl font-bold">Devices</h1>
+      <Button label="Add" icon="pi pi-plus" @click="openDialog" />
+    </div>
+
+    <Card v-if="devices.value?.length === 0">
+      <template #content>
+        <p class="text-center text-gray-500">
+          No devices yet
+        </p>
+      </template>
+    </Card>
+
+    <div class="grid gap-4">
+      <Card v-for="device in devices.value" :key="device.id">
+        <template #content>
+          <!-- content -->
+        </template>
+      </Card>
+    </div>
+  </div>
+</template>
+```
+
+### Status tag
+
+```vue
+<Tag
+  :value="conn.status"
+  :severity="conn.status === 'online' ? 'success' : 'secondary'"
+/>
+```
+
+## Computed paths – reactive parameters
+
+When paths depend on reactive values (route params, props), wrap them in `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)])
+```
+
+For conditional loading (e.g. only when logged in), return a falsy value:
+
+```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)])
+```
+
+## Related data – `.with()`
+
+Attach related objects to items in a single reactive query:
+
+```js
+path.blog.articles({})
+  .with(article => path.userIdentification.identification({
+    sessionOrUserType: article.authorType,
+    sessionOrUser: article.author
+  }).bind('authorProfile'))
+```
+
+Access: `article.authorProfile?.firstName`. Works with both `live()` and `RangeViewer`.
+
+## WorkingZone for async actions
+
+`ViewRoot` wraps every page in `<WorkingZone>`. Use `inject('workingZone')` for non-form button actions:
+
+```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: 'Published', life: 2000 })
+  })())
+}
+```
+
+This activates the global loading spinner/blur while the promise is pending.
+
+## Auth guards with `useClient`
+
+```js
+import { useClient } from '@live-change/vue3-ssr'
+const client = useClient()
+```
+
+- `client.value.user` – truthy when logged in
+- `client.value.roles` – array of roles (e.g. `['admin', 'owner']`)
+
+Use in templates:
+
+```vue
+<Button v-if="client.roles.includes('admin')" label="Admin" />
+<div v-if="!client.user">Please sign in</div>
+```
+
+## Locale and time
+
+- Call `useLocale().captureLocale()` in `App.vue` to save browser locale to backend.
+- Use `locale.localTime(date)` with vue-i18n's `d()` for SSR-safe date display.
+- `currentTime` from `@live-change/frontend-base` is a reactive ref that ticks every 500ms.
+- `useTimeSynchronization()` from `@live-change/vue3-ssr` corrects clock skew – use when timing is critical (countdowns, real-time events).
+
+## Analytics
+
+Use `analytics` from `@live-change/vue3-components`:
+
+```js
+import { analytics } from '@live-change/vue3-components'
+analytics.emit('article:published', { articleId: id })
+```
+
+Wire providers (PostHog, GA4) in a separate file imported from `App.vue`.
+
+## SSR and frontend configuration
+
+- Keep separate entry points for client and server:
+
+```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)
+```
+
+- Configure PrimeVue theme in one place (e.g. `config.js`) using `definePreset` and keep dark mode options consistent.
+
+## Discovering views and actions with `describe`
+
+Use the CLI `describe` command to find available views (for `live()`) and actions (for `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
+```
+
+This is the fastest way to discover what paths and actions are available, including those auto-generated by relations.

package/.claude/rules/live-change-service-structure.md

@@ -0,0 +1,89 @@
+---
+description: Rules for LiveChange service directory structure and file organization
+globs: **/services/**/*.js
+---
+
+# LiveChange Service Structure
+
+Every LiveChange service **must** be a directory, not a single file.
+
+## Required structure
+
+```
+server/services/<serviceName>/
+  definition.js   # creates app.createServiceDefinition({ name }) – nothing else
+  index.js        # imports definition, imports all domain files, exports definition
+  config.js       # optional – reads definition.config, exports resolved 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 (if needed)
+
+Reads `definition.config` set from `app.config.js`, resolves defaults, exports plain object.
+
+```js
+import definition from './definition.js'
+
+const { someOption = 'default' } = definition.config
+
+export default { someOption }
+```
+
+## 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'
+
+export const MyModel = definition.model({ name: 'MyModel', ... })
+
+definition.view({ name: 'myList', ... })
+definition.action({ name: 'doThing', ... })
+```
+
+## services.list.js import
+
+Always import from the directory index, not a flat file:
+
+```js
+import myService from './services/myService/index.js'   // correct
+import myService from './services/myService.js'         // wrong
+```
+
+## Reference implementation
+
+See `/home/m8/IdeaProjects/live-change/live-change-stack/services/stripe-service/` as the canonical example.

package/.claude/settings.json

@@ -0,0 +1,32 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls -d /home/m8/IdeaProjects/live-change/*/.claude/skills/)",
+      "Bash(ls -d /home/m8/IdeaProjects/live-change/*/.cursor/skills/)",
+      "Bash(node -e \"const p = require.resolve\\(''''@live-change/vue3-components''''\\); console.log\\(p\\)\")",
+      "Bash(find /home/m8/IdeaProjects/live-change/live-change-stack -path *vue3-components* -name *.js)",
+      "Read(//home/m8/IdeaProjects/**)",
+      "Bash(find /home/m8/IdeaProjects/live-change -name \"*.vue\" -type f ! -path \"*/node_modules/*\" ! -path \"*/.history/*\" -exec grep -l \"AutoField\" {})",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/skills/live-change-frontend-editor-form/SKILL.md /home/m8/IdeaProjects/live-change/.cursor/skills/live-change-frontend-editor-form.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/skills/live-change-frontend-action-form/SKILL.md /home/m8/IdeaProjects/live-change/.cursor/skills/live-change-frontend-action-form.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-frontend-vue-primevue.md /home/m8/IdeaProjects/live-change/auto-firma/.claude/rules/live-change-frontend-vue-primevue.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-frontend-vue-primevue.md /home/m8/IdeaProjects/live-change/automation/.claude/rules/live-change-frontend-vue-primevue.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-frontend-vue-primevue.md /home/m8/IdeaProjects/live-change/live-change-stack/frontend/frontend-template/.claude/rules/live-change-frontend-vue-primevue.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/skills/live-change-design-models-relations/SKILL.md /home/m8/IdeaProjects/live-change/.cursor/skills/live-change-design-models-relations.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/skills/live-change-design-actions-views-triggers/SKILL.md /home/m8/IdeaProjects/live-change/.cursor/skills/live-change-design-actions-views-triggers.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-backend-actions-views-triggers.md /home/m8/IdeaProjects/live-change/auto-firma/.claude/rules/live-change-backend-actions-views-triggers.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-backend-models-and-relations.md /home/m8/IdeaProjects/live-change/auto-firma/.claude/rules/live-change-backend-models-and-relations.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-backend-actions-views-triggers.md /home/m8/IdeaProjects/live-change/automation/.claude/rules/live-change-backend-actions-views-triggers.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-backend-models-and-relations.md /home/m8/IdeaProjects/live-change/automation/.claude/rules/live-change-backend-models-and-relations.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-backend-event-sourcing.md /home/m8/IdeaProjects/live-change/auto-firma/.claude/rules/live-change-backend-event-sourcing.md)",
+      "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-backend-event-sourcing.md /home/m8/IdeaProjects/live-change/automation/.claude/rules/live-change-backend-event-sourcing.md)",
+      "Bash(find /home/m8/IdeaProjects/live-change/live-change-stack/framework -type f \\\\\\(-name *.ts -o -name *.js \\\\\\))",
+      "Bash(find /home/m8/IdeaProjects/live-change/live-change-stack/services -type f -name *.js)",
+      "Bash(grep -r \"userItem\\\\|userProperty\" /home/m8/IdeaProjects/live-change/live-change-stack/services/user-service --include=*.js)"
+    ],
+    "additionalDirectories": [
+      "/home/m8/IdeaProjects/live-change/.claude/skills/create-skills-and-rules",
+      "/home/m8/IdeaProjects/live-change/.claude/rules"
+    ]
+  }
+}