@toa.io/extensions.configuration 1.0.0-alpha.272 → 1.0.0-alpha.274

package/ui/.agents/skills/svas/references/patterns.md

@@ -0,0 +1,95 @@
+# svas — advanced patterns
+
+Idioms for non-trivial usage. All build on `Maybe<T> = null | T | Error` and the `ok()` guard.
+
+## Derived `Maybe` stores
+
+Compute one async store from others with `svelte/store`'s `derived`. Forward `null`/`Error` early, and return a cleanup function when you subscribe to linked entities.
+
+```ts
+const internal = collection<Item>({ get: () => api.get(), persist: 'items' })
+
+export const items = derived<[typeof internal, typeof me], Maybe<Item[]>>(
+  [list, me],
+  ([$list, $me], set, update) => {
+    if (!ok($list)) return set($list)   // forward loading/error verbatim
+    if (!ok($me)) return set($me)
+
+    const items = $list.map((i) => map(i, $me.id))
+    set(items)
+
+    // live updates: re-emit when a linked entity changes
+    const unsubs = items.map((item) =>
+      accounts.get(item.owner).subscribe((account) =>
+        update((items) => {
+          if (!ok(items) || !ok(account)) return items
+          const i = items.findIndex((v) => v.owner === account.id)
+          if (i < 0) return items
+          items[i] = { ...items[i], account }
+          return items
+        })
+      )
+    )
+
+    return () => unsubs.forEach((u) => u())   // cleanup on unsubscribe
+  }
+)
+```
+
+Key moves: `if (!ok(x)) return set(x)` to forward non-resolved states, `update()` for incremental edits, return a teardown for any subscriptions you open.
+
+## Realtime event wiring
+
+> Usually used with antcn/@realtime
+
+Apply server events into stores with `sync` (collections/values-backed) or `.set` (standalone `values`). Mutating functions sync their own result so the optimistic and authoritative paths converge.
+
+```ts
+// collection backed by a values side store
+events.on('todos.sync', (todo) => sync(todos, todo))
+
+// standalone values map
+events.on('accounts.sync', (a) => accounts.set(a.id, a))
+
+export async function add(input: Input): Promise<Todo | Error> {
+  const me = await having(account)        // wait for auth
+  const res = await net.add(me.id, input)
+  if (res instanceof Error) return res     // error as value
+  sync(todos, res)                         // merge authoritative result
+  return res
+}
+```
+
+## Linked / enriched entities
+
+Join a network type with domain data. Use `.extract()` for a sync snapshot at map time; subscribe via `.get()` inside derived stores for live enrichment.
+
+```ts
+export interface Contact extends net.Contact {
+  account: Maybe<Account>
+}
+
+export function map(entry: net.Contact): Contact {
+  return { ...entry, account: accounts.extract(entry.owner) }  // sync snapshot
+}
+```
+
+Hold a `Maybe<T>` per link; never reach through it with `?.` — guard with `ok()` before use. For many links, `Record<string, Maybe<T>>` keyed by id.
+
+## Optimistic updates with rollback
+
+`values.set(key, v, { stash: true })` remembers the prior persisted value; `reset(key)` restores it if the request fails.
+
+```ts
+products.update(id, (product) => ({ ...product, ...properties }))
+
+const res = await net.patch(id, properties)
+
+if (res instanceof Error) return res
+else sync(products, res)
+```
+
+## `ensure` vs `having`
+
+- `ensure(store)` — **sync**, throws if `null`/`Error`. Use when the value must already exist (auth checks inside service functions called in response to user action).
+- `await having(store)` — **async**, waits for a resolved value, rejects on `Error`. Use at init time when the value may still be loading (initial data fetching when app is starting).

package/ui/.agents/skills/svintl/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: svintl
+description: >
+  svintl CLI for i18n — translations, locales, pluralization, mounts, building typed dictionaries. Triggers on `npx intl`, YAML locale files, intl directories, or any translation/i18n work in Svelte projects.
+---
+
+# svintl — i18n for Svelte
+
+CLI tool for managing internationalization dictionaries with automatic translation via OpenAI.
+
+## Core Rule
+
+The `*.yaml`, `built.js`, and `types.ts` files in intl directories are generated — they're edited through the `npx intl` CLI, not by hand.
+
+## CLI Commands
+
+```bash
+npx intl hola                               # init dictionaries (default: src/lib/intl/)
+npx intl hola -p ./custom/path              # init at custom path
+npx intl add key.path "Value" "context"     # add a new key — fails if it already exists; context optional
+npx intl set key.path "Updated value"       # update a key that already exists — fails if missing
+npx intl set "mount/key.path" "Value"       # target a mount with the mount/ prefix
+npx intl add key.path "Value" --debug       # --debug (add or set): print the OpenAI request first
+npx intl const key.path "Same everywhere"   # same value across all locales (no translation)
+npx intl unit items.count "item"            # pluralized entry (auto-generates plural forms)
+npx intl move old.key new.key               # rename key/branch
+npx intl del key.path                       # delete key/branch
+npx intl create es                          # add a locale (BCP 47 tag) — auto-translates the whole dictionary into it
+npx intl destroy es                         # delete locale
+npx intl mount foo ./any/path               # create empty mount
+npx intl import foo ./any/path              # adopt existing dict dir as mount, reconcile locales
+npx intl unmount foo                        # remove mount (keeps files)
+npx intl context "Project description"      # set project-wide translation guidance
+npx intl context --clear                    # clear project context
+npx intl genders he she none                # enable gender-aware translations (list the gender values)
+npx intl genders                            # print current gender values
+npx intl sync en key.path                   # reconcile: re-translate one key into all locales from source en
+npx intl sync en                            # reconcile: re-translate the whole dictionary from source en
+npx intl build                              # rebuild JS/TS from YAML
+```
+
+## Dictionary Format
+
+YAML with arbitrary nesting, strings at leaves:
+
+```yaml
+native: English
+example:
+  hello: "Hello world"
+```
+
+Usage: `{$dict.example.hello}`
+
+### Dynamic Values — Placeholders
+
+For simple cases the CLI auto-generates `!js` functions from placeholder syntax — no need to write them manually:
+
+```bash
+npx intl set greeting "Hello, {name}!"            # {name} → function param
+npx intl set joined "[names] joined {groupName}"  # [names] → Intl.ListFormat
+```
+
+For complex logic, pass `!js` functions via `intl set`:
+
+```bash
+npx intl set greeting '!js (count) => `${count || "No"} item${count === 1 ? "" : "s"}`'
+```
+
+Usage in components: `{$dict.greeting(user.name)}`
+
+**Keep the whole phrase in the dictionary.** Never split a sentence around a dynamic value in the template:
+
+```svelte
+<!-- ❌ Wrong: breaks the phrase for translators -->
+<strong>{brand}</strong>{$dict.form.destroyDescription}
+
+<!-- ✅ Right: one entry, function accepts the value -->
+{@html $dict.form.destroyDescription(brand)}
+```
+
+```bash
+npx intl set "apps/form.destroyDescription" \
+  '!js (brand) => `<strong>${brand}</strong> and all accumulated data will be permanently deleted.`'
+```
+
+When a name needs markup and is always at the start of the phrase across languages, put the tags inside the `!js` function and render with `{@html}` — escape user-controlled values before passing them in.
+
+### Pluralization
+
+Use `npx intl unit` — generates `Intl.PluralRules`-based functions:
+
+```bash
+npx intl unit items.count "item"
+```
+
+Produces:
+```yaml
+items:
+  count:
+    - one: item
+      other: items
+```
+
+Usage: `{$dict.items.count(count)}`
+
+Complex locales (Russian, Arabic) auto-get `few`, `many`, etc.
+
+### Genders
+
+When enabled (`npx intl genders he she none`), gender-dependent phrases become functions whose **last** argument is the gender (`'he' | 'she' | 'none'`) — the phrase's own arguments come first, e.g. `(name, gender) => …`. The listed values become the generated `Grammar` union.
+
+## Mounts
+
+Organize translations into separate directories:
+
+```bash
+npx intl mount admin ./src/features/admin/intl
+npx intl set "admin/dashboard.title" "Admin Dashboard"
+```
+
+Mount keys use `{mount}/` prefix in CLI commands.
+
+`mount` scaffolds an empty mount; `import` adopts a populated dir (with its own `context.yaml`) and reconciles its locales to the root — drops languages the root lacks, generates ones it lacks (translating the imported `inputs`), leaves shared locales untouched.
+
+## Import Pattern
+
+**Root dictionary:**
+```svelte
+<script lang="ts">
+  import { dict, locale } from '$lib/intl'
+</script>
+<h1>{$dict.example.hello}</h1>
+```
+
+**Mount dictionary:**
+```svelte
+<script lang="ts">
+  import { dict } from './intl'
+</script>
+<h1>{$dict.dashboard.title}</h1>
+```
+
+**Mount's `intl/index.ts`:**
+```typescript
+import { derived } from 'svelte/store'
+import { locale } from '$lib/intl'
+import { dictionaries } from './built.js'
+import type { Locale, Dictionary } from './types'
+
+const dict = derived(locale, ($locale) => dictionaries[$locale])
+export { dict, dictionaries, locale }
+export type { Locale, Dictionary }
+```
+
+## Context for Translation Accuracy
+
+```bash
+npx intl set app.welcome "Welcome" "greeting shown on homepage"
+npx intl context "B2B SaaS for enterprise users"
+```
+
+Context is stored in `context.yaml` and used by OpenAI when creating new locales.
+
+## Workflow
+
+1. Use `npx intl add/set/unit/const` to add/update translations
+2. Run `npx intl build` to generate JS/TS (often auto-runs)
+3. Import `dict` store in components
+4. Use `$dict.key.path` in templates
+
+## Avoid
+
+- **Editing YAML by hand** — go through the CLI
+- **`npx intl sync` for routine edits** — it's only for reconciling after a manual source edit; use `add`/`set` instead
+- **Non-BCP47 locale codes** — use valid tags like `en-US`, `es`, `pt-BR`
+- **Splitting phrases in the template** — don't concatenate a dynamic value with a dictionary suffix/prefix; use one `{placeholder}` / `!js` entry for the full sentence

package/ui/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/tools/hooks/guard-intl.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/ui/.codex/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "apply_patch|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)\"/tools/hooks/guard-intl.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/ui/.cursor/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "./tools/hooks/guard-intl.sh",
+        "matcher": "Write|Edit"
+      }
+    ]
+  }
+}

package/ui/.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY=<put your openai api key here>

package/ui/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "useTabs": false,
+  "singleQuote": true,
+  "printWidth": 100,
+  "semi": false,
+  "tabWidth": 2,
+  "bracketSameLine": true,
+  "htmlWhitespaceSensitivity": "ignore"
+}

package/ui/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+	"recommendations": [
+		"svelte.svelte-vscode",
+		"bradlc.vscode-tailwindcss",
+		"dbaeumer.vscode-eslint"
+	]
+}

package/ui/.vscode/settings.json

@@ -0,0 +1,27 @@
+{
+  "files.associations": {
+    "*.css": "tailwindcss"
+  },
+  "eslint.validate": [
+    "javascript",
+    "typescript",
+    "svelte"
+  ],
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "[svelte]": {
+    "editor.defaultFormatter": "svelte.svelte-vscode"
+  },
+  "html.autoClosingTags": false,
+  "cucumberautocomplete.strictGherkinCompletion": false,
+  "cucumberautocomplete.strictGherkinValidation": false,
+  "cucumberautocomplete.smartSnippets": true,
+  "cucumberautocomplete.onTypeFormat": true,
+  "editor.quickSuggestions": {
+    "comments": false,
+    "strings": true,
+    "other": true
+  }
+}

package/ui/AGENTS.md

@@ -0,0 +1,51 @@
+## Project Configuration
+
+- **Language**: TypeScript
+- **Package Manager**: npm
+- **Add-ons**: none
+
+---
+
+## Architecture
+
+Before making any changes to the codebase, **always refer to `architecture.md`** for:
+
+- Domain organization, layer responsibilities, and conventions
+- Component organization (domain vs shared)
+- Forms pattern and service connectors
+- Linked entities pattern
+- Svelte conventions (reactivity, navigation, persistent state, class merging)
+- Internationalization (i18n)
+- Testing (Playwright BDD structure, conventions, running tests)
+
+Understanding the architecture is essential for maintaining code quality and consistency.
+
+## Backend API
+
+This app is the configuration UI of the Toa runtime, and lives inside it: the backend is the
+repository around it.
+
+- The values are one ordinary component, `extensions/configuration/components/configuration.values`;
+  its `manifest.toa.yaml` declares the entity, the operations and the endpoints they are exposed
+  at. `GET /configuration/values/` lists every configured component, `GET /configuration/values/:component/`
+  answers `{ configuration, schema, epoch }`, and `POST` to the same address creates a new one.
+- Reading needs the `system:configuration:get` role and creating needs `system:configuration:create`.
+- A configuration is immutable: creating one replaces the whole of it. A secret is held as a
+  `$NAME` reference and is never shown — see `src/@/configuration/ui/read.ts`.
+- The HTTP protocol those endpoints speak — queries, errors, caching, authentication — is
+  documented in `extensions/exposition/documentation`.
+- The page is served by `extensions/configuration/source/UI.ts` out of `dist`, under the mount
+  path `/.configuration` on port `8003`. The API is on the app's own origin, except locally,
+  where it is `:8000` — see `src/config/index.ts`.
+
+## Verification
+
+Before calling a change done, verify it:
+
+- **`npm run check`** - Type and Svelte checks pass.
+- **`npm run format`** - Lint and format (eslint `--fix`).
+- **Check it in a browser** - Load the change in a headless browser and confirm it renders and behaves as intended. Use any available tool: `/agent-browser`, Chrome DevTools MCP, Playwright MCP.
+
+### Measure or Eyeball
+
+A running UI is inspected two ways: **measure** it or **eyeball** it. Measuring reads exact values from the live DOM — `evaluate` JS returning numbers (`getBoundingClientRect`, `getComputedStyle`, `elementFromPoint`) — and is the default for anything with a number: size, position, gap, color, font, real visibility. Eyeball only what the eye alone settles: broken layout at a glance, occlusion, whether the composition reads. A screenshot is a **witness, not a verdict** — it flags a suspicion; the measurement decides. Never read a number off a screenshot.