@live-change/frontend-template 0.9.198 → 0.9.199

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

@@ -0,0 +1,291 @@
+---
+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.
+
+### `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/skills/create-skills-and-rules.md

@@ -0,0 +1,196 @@
+---
+description: Create or update Claude Code skills and Cursor rules/skills with proper format and frontmatter
+---
+
+# Skill: create-skills-and-rules
+
+Use this skill when you need to **create or update skills and rules** for Claude Code (`.claude/`) and Cursor (`.cursor/`).
+
+## Directory structure
+
+```
+.claude/
+  rules/     *.md   – always-loaded project instructions
+  skills/    *.md   – step-by-step guides, invocable or auto-matched by description
+.cursor/
+  rules/     *.mdc  – Cursor rules with description/globs/alwaysApply frontmatter
+  skills/    *.md   – same content as .claude/skills/ (Cursor reads them as reference)
+```
+
+## Step 1 – Decide: rule or skill
+
+| Type | Purpose | When loaded |
+|---|---|---|
+| **Rule** | Constraints, conventions, best practices | Automatically, based on `globs` or `alwaysApply` |
+| **Skill** | Step-by-step implementation guide | When description matches task, or invoked via `/skill-name` |
+
+Rules say **what to do / not do**. Skills say **how to do it step by step**.
+
+## Step 2 – Create a Claude Code skill (`.claude/skills/<name>.md`)
+
+### Frontmatter
+
+```yaml
+---
+description: Short description of what this skill does and when to use it
+---
+```
+
+The `description` field is used by Claude to decide when to automatically apply the skill. Write it as a concise action phrase.
+
+### Optional frontmatter fields (for directory-based skills)
+
+If you use the directory format `.claude/skills/<name>/SKILL.md`:
+
+```yaml
+---
+name: my-skill
+description: What this skill does
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: Read, Grep, Bash
+context: fork
+agent: Explore
+argument-hint: [filename]
+model: sonnet
+---
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `name` | directory name | Slash command name (lowercase, hyphens, max 64 chars) |
+| `description` | – | When to use (Claude matches this to decide auto-invocation) |
+| `user-invocable` | `true` | Show in `/` menu |
+| `disable-model-invocation` | `false` | Prevent auto-loading by Claude |
+| `allowed-tools` | – | Tools allowed without asking (e.g. `Read, Grep, Bash`) |
+| `context` | – | Set to `fork` to run in isolated subagent |
+| `agent` | – | Subagent type when `context: fork` (`Explore`, `Plan`, etc.) |
+| `argument-hint` | – | Hint for autocomplete (e.g. `[issue-number]`) |
+| `model` | inherited | Model override (`sonnet`, `opus`, `haiku`) |
+
+### Dynamic substitutions in skill content
+
+- `$ARGUMENTS` – all arguments passed when invoking
+- `$ARGUMENTS[0]`, `$1` – specific argument by index
+- `${CLAUDE_SESSION_ID}` – current session ID
+- `${CLAUDE_SKILL_DIR}` – directory containing SKILL.md
+
+### Body structure
+
+```markdown
+---
+description: Build X with Y and Z
+---
+
+# Skill: my-skill-name (Claude Code)
+
+Use this skill when you build **X** using Y and Z.
+
+## When to use
+
+- Bullet list of scenarios
+
+## Step 1 – First step
+
+Explanation + code example.
+
+## Step 2 – Second step
+
+Explanation + code example.
+```
+
+Keep skills under 500 lines. Use clear step numbering. Include real code examples.
+
+## Step 3 – Create a Claude Code rule (`.claude/rules/<name>.md`)
+
+### Frontmatter
+
+```yaml
+---
+description: Short description of this rule's purpose
+globs: **/front/src/**/*.{vue,js,ts}
+---
+```
+
+| Field | Description |
+|---|---|
+| `description` | What this rule covers (used for matching) |
+| `globs` | File patterns that trigger this rule (e.g. `**/*.js`, `**/services/**/*.js`) |
+
+### Body structure
+
+```markdown
+---
+description: Rules for X development
+globs: **/*.js
+---
+
+# Title
+
+## Section 1
+
+- Rule bullet points
+- Code examples
+
+## Section 2
+
+- More rules
+```
+
+Rules are concise. Lead with the constraint, then show a code example.
+
+## Step 4 – Create Cursor rule (`.cursor/rules/<name>.mdc`)
+
+Same content as the Claude rule, but with Cursor-specific frontmatter:
+
+```yaml
+---
+description: Short description of this rule's purpose
+globs: **/front/src/**/*.{vue,js,ts}
+alwaysApply: false
+---
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `description` | – | What the rule does; Cursor uses this to decide when to apply |
+| `globs` | – | Comma-separated file patterns (e.g. `**/*.tsx, src/**/*.js`) |
+| `alwaysApply` | `false` | If `true`, applies to every session regardless of context |
+
+**Notes:**
+- Do NOT quote glob patterns in frontmatter
+- Keep rules short (target 25 lines, max 50 lines for best Cursor performance)
+- The `.mdc` extension is required for Cursor
+
+## Step 5 – Mirror Cursor skills (`.cursor/skills/<name>.md`)
+
+Copy the `.claude/skills/*.md` file directly to `.cursor/skills/`. Same content, same filename. Cursor reads these as reference documents.
+
+## Step 6 – Mirror to sub-projects
+
+If the project has sub-projects with their own `.claude/` and `.cursor/` directories, copy the files there too:
+
+```bash
+for dir in automation auto-firma; do
+  cp .claude/skills/my-skill.md "$dir/.claude/skills/"
+  cp .claude/skills/my-skill.md "$dir/.cursor/skills/"
+  cp .claude/rules/my-rule.md "$dir/.claude/rules/"
+  cp .cursor/rules/my-rule.mdc "$dir/.cursor/rules/"
+done
+```
+
+## Naming conventions
+
+- Use lowercase with hyphens: `live-change-frontend-editor-form.md`
+- Prefix with domain: `live-change-frontend-*`, `live-change-backend-*`
+- Skills describe actions: `*-editor-form`, `*-range-list`, `*-action-buttons`
+- Rules describe scope: `*-vue-primevue`, `*-models-and-relations`
+
+## Checklist
+
+- [ ] Frontmatter with `description` in every file
+- [ ] `.claude/skills/*.md` created
+- [ ] `.cursor/skills/*.md` mirrored (same content)
+- [ ] `.claude/rules/*.md` created (if rule)
+- [ ] `.cursor/rules/*.mdc` created with `globs` + `alwaysApply` (if rule)
+- [ ] Sub-projects updated (automation, auto-firma)