@treenity/core 1.0.48 → 3.0.1

package/src/mod/docs/06-actions.md

@@ -0,0 +1,193 @@
+# 06 — Экшены
+
+Экшен — метод класса компонента. Сервер исполняет его через Immer draft, патчи
+автоматически сохраняются. Если данные не менялись — store.set() не вызывается.
+
+## Шаг 1: определи экшены как методы класса
+
+```ts
+import { registerComp } from '#comp';
+
+export class OrderStatus {
+  value: 'incoming' | 'kitchen' | 'ready' = 'incoming';
+
+  advance() {
+    // this — Immer draft компонента
+    if (this.value === 'incoming') this.value = 'kitchen';
+    else if (this.value === 'kitchen') this.value = 'ready';
+  }
+}
+
+registerComp('order.status', OrderStatus);
+```
+
+Всё. `registerComp` автоматически регистрирует `action:advance` из метода.
+
+## Шаг 2: вызов из React-вьюшки
+
+```tsx
+import { useComp } from '#front/hooks';
+import { OrderStatus } from './types';
+
+function OrderCard({ path }: { path: string }) {
+  const status = useComp(path, OrderStatus);
+  // status.value    — live данные из кэша (реактивно)
+  // status.advance() — вызывает trpc.execute, получает ответ
+
+  return (
+    <button onClick={() => status.advance()}>
+      {status.value} →
+    </button>
+  );
+}
+```
+
+`useComp(path, Class, key?)` — одна точка для данных и действий.
+- `key` нужен только если на ноде несколько компонентов одного `$type`.
+
+## Шаг 3: вызов из сервиса / серверного кода
+
+```ts
+import { createServerNodeClient } from '#server/actions';
+import { OrderStatus } from '../orders/types';
+
+register('my.service', 'service', async (node, ctx) => {
+  const nc = createServerNodeClient(ctx.store);
+
+  await nc('/orders/123').get(OrderStatus).advance();
+  // Typed: IDE подсказывает методы и аргументы
+});
+```
+
+`key` можно опустить: если ключ поля совпадает с последним сегментом `$type`
+(`'order.status'` → `'status'`), сканирование находит компонент автоматически.
+
+## Методы с аргументами
+
+```ts
+export class PultConfig {
+  risk = 0.5;
+
+  setRisk(data: { value: number }) {
+    this.risk = Math.max(0, Math.min(1, data.value));
+  }
+}
+```
+
+```tsx
+// React:
+const cfg = useComp(path, PultConfig);
+<Fader onChange={v => cfg.setRisk({ value: v })} />
+
+// Сервис:
+await nc(path).get(PultConfig).setRisk({ value: 0.1 });
+```
+
+## Сигнатура = порты + параметры
+
+Тип `data`-аргумента метода — единый источник правды для двух контекстов:
+
+```ts
+class Invoice {
+  static $type = 'billing.invoice'
+
+  async charge(data: { amount: number, account: Account, user?: User }) {
+    data.account.debit(data.amount)
+    data.user?.notify('charged')
+  }
+}
+```
+
+| В коде | В визуальном редакторе |
+|--------|----------------------|
+| `amount: number` — параметр, передаётся при вызове | Поле ввода на кубике |
+| `account: Account` — typed значение | **Порт** — входной разъём типа Account, тянешь провод |
+| `user?: User` — optional параметр | **Опциональный порт** — можно не подключать |
+
+**Вызов из кода** — обычный typed call:
+```ts
+invoice.charge({ amount: 10, account: user.account })
+```
+
+**Компиляция графа** — визуальный редактор собирает значения с подключённых портов:
+```ts
+// wired connections → data object:
+invoice.charge({
+  amount: amountNode.value,
+  account: getComp(acmeNode, Account),
+})
+```
+
+Одна TypeScript-сигнатура, два мира. TypeScript проверяет типы при компиляции,
+JSON Schema генерируется для AI/валидации. Без отдельного DSL для портов.
+
+## Async-методы и доступ к store
+
+> **Правило:** `getCtx()` вызывай только синхронно на первой строке метода — до первого `await`/`yield`.
+> После `await` контекст уже не валиден (async stack ушёл).
+
+
+
+```ts
+import { getCtx } from '#comp';
+
+export class PultConfig {
+  async rebalance() {
+    const { node, store } = getCtx(); // ТОЛЬКО на первой строке — до первого await
+
+    const { items: markets } = await store.getChildren(`${node.$path}/markets`);
+    for (const m of markets) {
+      // ...
+    }
+    return { rebalanced: markets.length };
+  }
+}
+```
+
+## Generator-экшены — стримят результаты клиенту
+
+```ts
+export class Builder {
+  async *build(data: { count: number }) {
+    const { node, store, signal } = getCtx(); // ТОЛЬКО здесь — до любого await/yield
+
+    for (let i = 0; i < data.count; i++) {
+      if (signal.aborted) return;
+      const item = await buildItem(i);
+      await store.set(item);
+      yield item; // нода → клиент кладёт в кэш
+    }
+  }
+}
+```
+
+```ts
+// Подписка на стрим:
+trpc.streamAction.subscribe({ path, action: 'build', data: { count: 10 } }, {
+  onData(item) { /* nodes → cache */ },
+});
+```
+
+---
+
+## Справка: низкоуровневые вызовы
+
+Используй только если `useComp`/`createServerNodeClient` не подходят
+(generic Inspector, MCP, внешние интеграции).
+
+```ts
+// Прямой вызов (type scan без key):
+await executeAction(store, path, 'order.status', undefined, 'advance');
+
+// С конкретным key:
+await executeAction(store, path, 'order.status', 'status', 'advance');
+
+// Node-level (без компонента):
+await executeAction(store, path, undefined, undefined, 'doStuff');
+
+// tRPC напрямую:
+trpc.execute.mutate({ path, type: 'order.status', action: 'advance' });
+trpc.execute.mutate({ path, type: 'order.status', key: 'status', action: 'advance' });
+```
+
+Resolution: key → node[key] + verify $type; type only → findCompByType scan; neither → node.$type scan.

package/src/mod/docs/07-realtime.md

@@ -0,0 +1,108 @@
+# 07 — Подписки и React
+
+## Серверная сторона
+
+```ts
+import { withSubscriptions, type ReactivStore, type NodeEvent } from '#server/sub';
+
+type NodeEvent =
+  | { type: 'set';    path: string; node: NodeData; patches?: Patch[] }
+  | { type: 'patch';  path: string; patches: Patch[] }
+  | { type: 'remove'; path: string };
+
+const reactive: ReactivStore = withSubscriptions(store);
+
+const unsub = reactive.subscribe('/tasks', (event: NodeEvent) => {
+  // срабатывает на /tasks, /tasks/1, /tasks/1/sub, ...
+});
+unsub();
+```
+
+В сервисе store уже реактивный. `store.set()` / `store.remove()` автоматически нотифицируют подписчиков.
+
+## CDC Matrix (Query Mounts)
+
+При store.set() подписки автоматически проверяют все активные query mount-ы. Если нода вошла/вышла из фильтра — генерируются `addVps` / `rmVps` в событии. Клиентский кэш автоматически добавляет/убирает ноду из виртуальных папок.
+
+## React хуки
+
+```ts
+import { useNode, useChildren, useComponent, useAction, useNodeCount } from '#front/hooks';
+
+const [node, setNode] = useNode('/tasks/1');
+await setNode({ ...node, title: 'Updated' }); // optimistic → server → refetch
+
+const children = useChildren('/tasks', {
+  watch: true,       // подписаться на изменения существующих
+  watchNew: true,    // подписаться на появление новых
+  limit: 50,
+});
+
+const [comp, setComp] = useComponent('/tasks/1', 'status');
+await setComp({ $type: 'status', value: 'done' });
+
+const results = useAction('/dashboard', 'stats');
+const count = useNodeCount();
+```
+
+## Рендер через контекст
+
+```tsx
+import { Render, RenderContext, NodeProvider, useCurrentNode, useTreeContext } from '#contexts/react';
+
+<Render value={component} onChange={handler} />
+
+<RenderContext name="react:compact">
+  <Render value={component} />  {/* ищет react:compact → react → default */}
+</RenderContext>
+
+function MyRenderer({ value, onChange }) {
+  const node = useCurrentNode();
+  const context = useTreeContext();
+  return <div>{value.title}</div>;
+}
+```
+
+## react:list — самодостаточные list-item компоненты
+
+```tsx
+import type { View } from '@treenity/react/context';
+
+// View для default — value: ComponentData (базовый тип, есть $type)
+const DefaultListItem: View<ComponentData> = ({ value, ctx }) => {
+  const node = ctx!.node;
+  return (
+    <div className="child-card" onClick={() => navigate(node.$path)}>
+      <span className="child-icon">{typeIcon(node.$type)}</span>
+      <div className="child-info">
+        <span className="child-name">{pathName(node.$path)}</span>
+        <span className="child-type">{node.$type}</span>
+      </div>
+      <span className="child-chevron">&#8250;</span>
+    </div>
+  );
+};
+register('default', 'react:list', DefaultListItem);
+```
+
+Fallback: `react:list` → `default@react:list` → strip `:list` → `react`.
+
+## Нода КАК компонент — flat fields
+
+Когда `node.$type` совпадает с `$type` компонента, нода **сама является** компонентом. Поля лежат плоско:
+
+```ts
+import { createNode } from '#core';
+
+// Правильно — createNode создаёт типизированную ноду
+await store.set(createNode('/bot', 'brahman.bot', { token: '...', alias: '@bot' }));
+
+// Неправильно — вложенный компонент с тем же $type что и нода
+await store.set(createNode('/bot', 'brahman.bot', {
+  config: { $type: 'brahman.bot', token: '...' },  // WRONG: дублирует $type
+}));
+```
+
+## Views — read-only
+
+View (`react` контекст) — только отображение. Редактирование — через NodeEditor (edit panel + schema forms).

package/src/mod/docs/08-services.md

@@ -0,0 +1,35 @@
+# 08 — Сервисы
+
+Фоновые процессы: боты, сенсоры, воркеры. `register(type, "service", handler)` → возвращает `{ stop() }`.
+
+```ts
+import { register, createNode, type NodeData } from '#core';
+import { type ServiceHandle, type ServiceCtx } from '#contexts/service';
+
+register('my-worker', 'service', async (node: NodeData, ctx: ServiceCtx) => {
+  const timer = setInterval(async () => {
+    await ctx.store.set(createNode(
+      `${node.$path}/${Date.now()}`,
+      'tick',
+      { ts: Date.now() },
+    ));
+  }, 5000);
+
+  return {
+    stop: async () => clearInterval(timer),
+  } satisfies ServiceHandle;
+});
+```
+
+## Автозапуск
+
+Создай ref-ноду в `/sys/autostart`:
+
+```ts
+import { createNode } from '#core';
+
+await store.set(createNode('/my-worker', 'my-worker'));
+await store.set(createNode('/sys/autostart/my-worker', 'ref', { $ref: '/my-worker' }));
+```
+
+При старте сервера `startServices(store)` обходит `/sys/autostart`, резолвит refs, вызывает service-хэндлеры.

package/src/mod/docs/09-mounts.md

@@ -0,0 +1,43 @@
+# 09 — Mount-адаптеры
+
+Маршрутизация поддеревьев к другим бэкендам. Всё под `/mount-point/*` обслуживается подключённым Store.
+
+```ts
+register('my-adapter', 'mount', async (config, parentStore, ctx, globalStore) => {
+  return createMongoStore(config.uri, config.db, config.col);
+});
+```
+
+Нода с маунтом:
+
+```ts
+await store.set(createNode('/external', 'my-adapter', {
+  connection: { $type: 'connection', uri: '...', db: 'x', col: 'y' },
+  mount: { $type: 'my-adapter' },
+}));
+// Всё под /external/* теперь идёт в Mongo-коллекцию
+```
+
+## Встроенные маунты
+
+| Тип | Назначение |
+|-----|-----------|
+| `t.mount.mongo` | MongoDB-коллекция |
+| `t.mount.fs` | Файловая система |
+| `t.mount.memory` | In-memory (volatile) |
+| `t.mount.overlay` | Overlay двух store |
+| `t.mount.query` | Виртуальная папка с sift-фильтром |
+| `t.mount.types` | Интроспекция registry |
+
+## Query Mounts — виртуальные папки
+
+```ts
+await store.set(createNode('/orders/incoming', 't.mount.query', {
+  mount: {
+    $type: 't.mount.query',
+    source: '/orders/data',
+    match: { status: { value: 'incoming' } },
+  },
+}));
+// GET /orders/incoming → только ноды из /orders/data с status.value === 'incoming'
+```

package/src/mod/docs/10-acl.md

@@ -0,0 +1,60 @@
+# 10 — ACL, валидация, volatile
+
+## ACL
+
+```ts
+import { R, W, A, S, type GroupPerm } from '#core';
+
+// R=1 Read, W=2 Write, A=4 Admin, S=8 Subscribe
+// p > 0: allow bits
+// p = 0: deny all (sticky)
+// p < 0: deny specific bits (sticky)
+
+node.$acl = [
+  { g: 'admin',         p: R | W | A | S }, // всё
+  { g: 'authenticated', p: R | S },          // чтение + подписка
+  { g: 'public',        p: R },              // только чтение
+  { g: 'banned',        p: 0 },              // блок (sticky)
+];
+node.$owner = 'user123';
+```
+
+Уровни: node-level (`$acl`, `$owner`) + component-level (`register(type, "acl", handler)`).
+
+ACL на тип по умолчанию:
+
+```ts
+register('secret', 'acl', () => [{ g: 'admin', p: R | W | A | S }]);
+```
+
+## Валидация
+
+`withValidation(store)` — write-barrier: проверяет компоненты против JSON Schema перед store.set().
+
+```ts
+import { withValidation } from '#server/validate';
+
+const validated = withValidation(store);
+// validated.set() бросит ошибку, если компонент не проходит schema
+```
+
+## Volatile Nodes
+
+Ноды с `$volatile: true` хранятся только в памяти, не персистятся на диск/Mongo.
+
+```ts
+import { withVolatile } from '#server/volatile';
+
+const store = withVolatile(backingStore);
+await store.set(createNode('/temp', 'session', { $volatile: true }));
+```
+
+## Server Pipeline
+
+```
+bootstrap store (fs/mongo)
+  → mountable (mount system)
+    → volatile (memory-only nodes)
+      → validated (JSON Schema check)
+        → subscriptions (events + CDC)
+```

package/src/mod/docs/11-server.md

@@ -0,0 +1,62 @@
+# 11 — Server: tRPC, MCP, Seed
+
+## Seed
+
+`seed(store)` — идемпотентно создаёт системные ноды:
+- `/sys`, `/sys/autostart`
+- `/auth`, `/auth/users`, `/auth/sessions`
+- `/mnt/orders`, `/entities`, `/orders`
+
+## MCP Server
+
+Инструменты (без ACL):
+
+```ts
+get_node(path)                      // → NodeData | undefined
+list_children(path, depth?)         // → Page<NodeData>
+set_node(path, type, components?)   // read-merge-write → NodeData
+remove_node(path)                   // → boolean
+execute(path, action, component?, data?)  // → result
+```
+
+## tRPC Router — все endpoints
+
+### Чтение
+```ts
+get({ path, watch? })                                    // → NodeData | undefined
+getChildren({ path, limit?, offset?, watch?, watchNew? }) // → Page<NodeData>
+```
+
+### Запись
+```ts
+set({ node })                                    // → void
+setComponent({ path, name, data, rev? })         // → void
+remove({ path })                                 // → boolean
+```
+
+### Экшены
+```ts
+execute({ path, type?, key?, action, data? })     // → result
+streamAction({ path, type?, key?, action, data? }) // → AsyncIterable (subscription)
+```
+
+### Шаблоны
+```ts
+getTemplates()                                   // → NodeData[]
+applyTemplate({ templatePath, targetPath })      // → { applied, blocks }
+```
+
+### Аутентификация
+```ts
+register({ userId, password })   // → { token, userId }
+login({ userId, password })      // → { token, userId }
+anonLogin()                      // → { token, userId }
+me()                             // → { userId } | null
+```
+
+### Watch
+```ts
+unwatch({ paths })               // отписаться от exact-path
+unwatchChildren({ paths })       // отписаться от prefix-watch
+events                           // SSE поток NodeEvent
+```

package/src/mod/docs/12-conventions.md

@@ -0,0 +1,108 @@
+# 12 — Naming, стили, правила
+
+## Naming Convention
+
+```
+string          → core built-in: dir, ref, root, user, type, mount-point, autostart
+t.*             → treenity infrastructure: t.mount.fs, t.mount.mongo, t.llm
+{vendor}.*      → package types: acme.block.hero, acme.bot, order.status
+```
+
+Разделитель: только `.` (не `/`, не `@`, не `:`).
+Паттерн: `{namespace}.{category}.{name}`.
+
+## Стили
+
+Используй **Tailwind CSS** классы, не inline styles. Tailwind 4 + `@tailwindcss/vite` подключены.
+
+```tsx
+// Правильно
+<div className="flex gap-2 text-sm px-2 py-1 bg-muted rounded">
+
+// Неправильно
+<div style={{ display: 'flex', gap: 8, fontSize: 13 }}>
+```
+
+Для составных компонентов используй shadcn/ui (`@/components/ui/*`): `Badge`, `Button`, `Input`, `Card` и др.
+
+## Контексты — сводная таблица
+
+| Контекст        | Тип handler                      | Назначение                  |
+| --------------- | -------------------------------- | --------------------------- |
+| `schema`        | `() => JSONSchema`               | JSON Schema для UI-форм     |
+| `react`         | `FC<{ value, onChange? }>`       | React-компонент             |
+| `react:compact` |                                  | fallback к `react`          |
+| `text`          | `(data) => string`              | Текстовый рендер            |
+| `action:*`      | `(ctx: ActionCtx, data) => any` | Серверный экшен             |
+| `service`       | `(node, ctx) => ServiceHandle`  | Фоновый сервис              |
+| `mount`         | `(config, parent, ctx, global) => Store` | Mount-адаптер       |
+| `acl`           | `() => GroupPerm[]`              | ACL по умолчанию для типа   |
+| `class`         | `Class<T>`                       | Registered component class  |
+| `telegram`      | `(node, tgCtx) => void`         | Telegram-хэндлер            |
+
+## TypeScript — дисциплина типов
+
+**`as any` ЗАПРЕЩЁН.** Не "только в emergency" — НИКОГДА. Если типы не сходятся, чини типы. `as any` прячет баги, ломает inference, расползается как рак.
+
+Допустимые касты:
+- `as const` — сужение литерала
+- `as 'idle'` — сужение к известному union-варианту
+- `as SensorReading` — сужение к конкретному типу (когда ты знаешь что это он)
+
+**Создание нод — ВСЕГДА через `createNode()`:**
+```ts
+// Со строковым типом — T выводится из data:
+await store.set(createNode('/path', 'my.type', { field: 'value' }));
+
+// С Class<T> — data проверяется по полям класса (Partial<T>):
+await store.set(createNode('/sensors/temp', SensorConfig, { interval: 10, source: 'api' }));
+//                                                         ^^^^^^^^ autocomplete + type check
+
+// С компонентами:
+await store.set(createNode('/path', 'sensor', { interval: 5 }, {
+  config: { $type: 'sensor.config', source: 'api' },
+}));
+
+// ЗАПРЕЩЕНО — as NodeData убивает типизацию
+await store.set({ $path: '/path', $type: 'my.type', field: 'value' } as NodeData);
+```
+
+**Views — типизированные через `View<T>`:**
+```tsx
+import type { View } from '@treenity/react/context';
+
+// value — данные компонента. path — через ctx!.node.$path
+const MyView: View<MyType> = ({ value, ctx }) => { ... };
+
+// register принимает Class<T> — T пробрасывается автоматически
+register(MyType, 'react', MyView);
+```
+
+**Запрещённые паттерны:**
+- `value as NodeData & MyType` — value УЖЕ типизирован через View<T>
+- `(node as any).field` — используй `getComp(node, Class)` для типобезопасного доступа
+- `register('type', 'react', handler as any)` — используй `register(Class, 'react', handler)`
+
+## Ошибки
+
+```ts
+import { OpError } from '#server/errors';
+
+// Коды: 'NOT_FOUND' | 'BAD_REQUEST' | 'CONFLICT' | 'FORBIDDEN'
+throw new OpError('NOT_FOUND', 'Node not found: /path');
+throw new OpError('CONFLICT', 'Stale revision');
+```
+
+`OpError` → автоматически маппится на tRPC error (NOT_FOUND → 404, CONFLICT → 409 и т.д.).
+
+## Архитектурные правила
+
+1. **Core < 500 строк.** Всё остальное — в контекстах и модах
+2. **Zero dependencies в core.** Только TypeScript
+3. **Layer model:** нижний слой не знает о верхнем
+4. **Sealed registry:** нет переопределений, только расширение
+5. **Компонент знает только свои данные.** Соседи — через `needs`
+6. **Refs только на ноды** (`$ref: "/path"`), никогда глубокие пути
+7. **Дети — по path prefix query**, не хранятся в родителе
+8. **`$` prefix — системные поля.** В Mongo `$` ↔ `_` автоматически
+9. **Fallback контекстов:** exact → default@same-ctx → strip suffix → recurse → null