@treenity/core 1.0.48 → 3.0.0

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

@@ -0,0 +1,100 @@
+# 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
+function DefaultListItem({ value }: { value: NodeData }) {
+  return (
+    <div className="child-card" onClick={() => navigate(value.$path)}>
+      <span className="child-icon">{typeIcon(value.$type)}</span>
+      <div className="child-info">
+        <span className="child-name">{pathName(value.$path)}</span>
+        <span className="child-type">{value.$type}</span>
+      </div>
+      <span className="child-chevron">&#8250;</span>
+    </div>
+  );
+}
+register('default', 'react:list', DefaultListItem as any);
+```
+
+Fallback: `react:list` → `default@react:list` → strip `:list` → `react`.
+
+## Нода КАК компонент — flat fields
+
+Когда `node.$type` совпадает с `$type` компонента, нода **сама является** компонентом. Поля лежат плоско:
+
+```ts
+// Правильно
+await store.set({ $path: '/bot', $type: 'brahman.bot', token: '...', alias: '@bot' } as NodeData);
+
+// Неправильно
+await store.set({ $path: '/bot', $type: 'brahman.bot', config: { $type: 'brahman.bot', token: '...' } });
+```
+
+## Views — read-only
+
+View (`react` контекст) — только отображение. Редактирование — через NodeEditor (edit panel + schema forms).

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

@@ -0,0 +1,33 @@
+# 08 — Сервисы
+
+Фоновые процессы: боты, сенсоры, воркеры. `register(type, "service", handler)` → возвращает `{ stop() }`.
+
+```ts
+import { register, 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({
+      $path: `${node.$path}/${Date.now()}`,
+      $type: 'tick',
+      ts: Date.now(),
+    } as NodeData);
+  }, 5000);
+
+  return {
+    stop: async () => clearInterval(timer),
+  } satisfies ServiceHandle;
+});
+```
+
+## Автозапуск
+
+Создай ref-ноду в `/sys/autostart`:
+
+```ts
+await store.set({ $path: '/my-worker', $type: 'my-worker' } as NodeData);
+await store.set({ $path: '/sys/autostart/my-worker', $type: 'ref', $ref: '/my-worker' } as NodeData);
+```
+
+При старте сервера `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({ $path: '/temp', $type: 'session', $volatile: true } as NodeData);
+```
+
+## 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,65 @@
+# 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-хэндлер            |
+
+## Ошибки
+
+```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

package/src/mod/docs/13-example.md

@@ -0,0 +1,132 @@
+# 13 — Полный пример: мод от начала до конца
+
+## 1. types.ts — определение компонентов
+
+```ts
+// src/mods/sensor/types.ts
+import { getCtx, registerComp } from '#comp';
+import { join, type NodeData } from '#core';
+
+export class SensorConfig {
+  /** @title Интервал @description Секунды между замерами */
+  interval = 5;
+  /** @title Источник */
+  source = '';
+
+  updateInterval(data: { interval: number }) {
+    this.interval = data.interval;
+  }
+
+  async history() {
+    const { node, store } = getCtx();
+    const { items } = await store.getChildren(node.$path, { limit: 100 });
+    return { items: items.map(n => ({ value: (n as any).value, ts: (n as any).ts })) };
+  }
+}
+
+registerComp('sensor.config', SensorConfig);
+
+export class SensorReading {
+  value = 0;
+  ts = 0;
+}
+
+registerComp('sensor.reading', SensorReading);
+```
+
+## 2. service.ts — фоновый процесс
+
+```ts
+// src/mods/sensor/service.ts
+import { register, type NodeData } from '#core';
+import { getComp } from '#comp';
+import { type ServiceHandle, type ServiceCtx } from '#contexts/service';
+import { SensorConfig } from './types';
+
+register('sensor', 'service', async (node: NodeData, ctx: ServiceCtx) => {
+  const config = getComp(node, SensorConfig);
+  const interval = (config?.interval ?? 5) * 1000;
+
+  const timer = setInterval(async () => {
+    await ctx.store.set({
+      $path: `${node.$path}/${Date.now()}`,
+      $type: 'sensor.reading',
+      value: Math.random() * 100,
+      ts: Date.now(),
+    } as NodeData);
+  }, interval);
+
+  return { stop: async () => clearInterval(timer) } satisfies ServiceHandle;
+});
+```
+
+## 3. view.tsx — React-рендер
+
+```tsx
+// src/mods/sensor/view.tsx
+import { register, type ComponentData } from '#core';
+import { useCurrentNode } from '#contexts/react';
+import { useChildren } from '#front/hooks';
+
+register('sensor.config', 'react', ({ value, onChange }) => {
+  return (
+    <div>
+      <label>Interval: {(value as any).interval}s</label>
+      <label>Source: {(value as any).source}</label>
+    </div>
+  );
+});
+
+register('sensor', 'react', ({ value }) => {
+  const node = useCurrentNode();
+  const readings = useChildren(node.$path, { limit: 10, watchNew: true });
+
+  return (
+    <div>
+      <h3>Sensor: {node.$path}</h3>
+      {readings.map(r => (
+        <div key={r.$path}>
+          {(r as any).value?.toFixed(1)} @ {new Date((r as any).ts).toLocaleTimeString()}
+        </div>
+      ))}
+    </div>
+  );
+});
+```
+
+## 4. schemas.ts — JSON Schema
+
+```ts
+// src/mods/sensor/schemas.ts
+import { register } from '#core';
+
+register('sensor.config', 'schema', () => ({
+  title: 'Sensor Config',
+  properties: {
+    interval: { type: 'number', title: 'Interval (sec)', minimum: 1 },
+    source: { type: 'string', title: 'Source URL' },
+  },
+}));
+```
+
+## 5. Регистрация
+
+```ts
+// src/mods/index.ts — добавить:
+import './sensor/types';
+import './sensor/service';
+
+// src/mods/views.ts — добавить:
+import './sensor/view';
+import './sensor/schemas';
+```
+
+## 6. Seed-данные
+
+```ts
+await store.set({ $path: '/sensors/temp', $type: 'sensor',
+  config: { $type: 'sensor.config', interval: 10, source: 'internal' },
+} as NodeData);
+
+await store.set({ $path: '/sys/autostart/temp-sensor', $type: 'ref', $ref: '/sensors/temp' } as NodeData);
+```