@treenity/core 1.0.47 → 3.0.0

package/src/mod/discover.ts

@@ -0,0 +1,100 @@
+// Treenity Module Discovery
+// npm: scan node_modules for packages with "treenity" field
+// local: scan dir for subdirs with index.ts exporting defineMod()
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { ModManifest, TreenityMod } from './types';
+
+// ── npm discovery ──
+
+export async function discoverMods(nodeModulesPath: string): Promise<ModManifest[]> {
+  const results: ModManifest[] = [];
+  let entries: string[];
+
+  try {
+    entries = await readdir(nodeModulesPath);
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (entry.startsWith('.')) continue;
+
+    // Scoped packages: @scope/pkg
+    if (entry.startsWith('@')) {
+      let scoped: string[];
+      try {
+        scoped = await readdir(join(nodeModulesPath, entry));
+      } catch { continue; }
+
+      for (const sub of scoped) {
+        const m = await readManifest(join(nodeModulesPath, entry, sub));
+        if (m) results.push(m);
+      }
+      continue;
+    }
+
+    const m = await readManifest(join(nodeModulesPath, entry));
+    if (m) results.push(m);
+  }
+
+  return results;
+}
+
+async function readManifest(packageDir: string): Promise<ModManifest | null> {
+  try {
+    const raw = await readFile(join(packageDir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    if (!pkg.treenity) return null;
+
+    const t = pkg.treenity;
+    return {
+      name: t.name ?? pkg.name,
+      version: t.version ?? pkg.version ?? '0.0.0',
+      types: t.types,
+      dependencies: t.dependencies,
+      server: t.server,
+      client: t.client,
+      seed: t.seed,
+      packagePath: packageDir,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ── Local discovery (server-side, dynamic import) ──
+
+export async function discoverLocalMods(modsDir: string): Promise<TreenityMod[]> {
+  const results: TreenityMod[] = [];
+  let entries: import('node:fs').Dirent[];
+
+  try {
+    entries = await readdir(modsDir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+
+    const indexPath = join(modsDir, entry.name, 'index.ts');
+
+    try {
+      await stat(indexPath);
+    } catch {
+      continue; // no index.ts — not a mod
+    }
+
+    try {
+      const exported = await import(indexPath);
+      const mod = exported.default as TreenityMod;
+      if (mod?.name) results.push(mod);
+    } catch {
+      // bad index.ts — skip silently
+    }
+  }
+
+  return results;
+}

package/src/mod/docs/00-index.md

@@ -0,0 +1,19 @@
+# Treenity Mods — документация
+
+| # | Файл | Тема |
+|---|------|------|
+| 01 | [01-primitives.md](01-primitives.md) | Три примитива, структура мода, dev workflow |
+| 02 | [02-core-api.md](02-core-api.md) | Core API: ноды, компоненты, ссылки, пути |
+| 03 | [03-registry.md](03-registry.md) | Registry — система контекстов, fallback, introspection |
+| 04 | [04-store.md](04-store.md) | Store: интерфейс, OCC, реализации, комбинаторы, query |
+| 05 | [05-comp.md](05-comp.md) | registerComp, getCtx, needs, type-safe доступ, JSDoc→Schema |
+| 06 | [06-actions.md](06-actions.md) | Экшены: execute/call, generator, вызов с клиента |
+| 07 | [07-realtime.md](07-realtime.md) | Подписки, CDC, React хуки, рендер через контекст |
+| 08 | [08-services.md](08-services.md) | Сервисы, автозапуск |
+| 09 | [09-mounts.md](09-mounts.md) | Mount-адаптеры, query mounts |
+| 10 | [10-acl.md](10-acl.md) | ACL, валидация, volatile, server pipeline |
+| 11 | [11-server.md](11-server.md) | tRPC endpoints, MCP, seed |
+| 12 | [12-conventions.md](12-conventions.md) | Naming, стили, архитектурные правила |
+| 13 | [13-example.md](13-example.md) | Полный пример мода от начала до конца |
+| 14 | [14-mod-format.md](14-mod-format.md) | npm-модули: формат, discovery, загрузка, optimistic updates |
+| 15 | [15-documenting-types.md](15-documenting-types.md) | JSDoc-аннотации: теги, форматы, примеры, промпт для LLM |

package/src/mod/docs/01-primitives.md

@@ -0,0 +1,38 @@
+# 01 — Три примитива
+
+```
+Node      = { $path, $type, ...components }   // сущность в дереве
+Component = { $type, ...data }                 // именованный аспект ноды
+Context   = register(type, context, handler)   // поведение типа в контексте
+```
+
+Нода — это `$path` + `$type` + произвольные компоненты. Компонент — именованное поле с `$type`. Контекст привязывает поведение (рендер, экшен, сервис) к типу.
+
+Системные поля: `$path`, `$type`, `$rev` (OCC), `$owner`, `$acl`.
+
+## Структура мода
+
+```
+src/mods/my-mod/
+  types.ts      — registerComp() — классы компонентов, данные + экшены
+  action.ts     — register(type, 'action:name', handler) — node-level экшены
+  schemas.ts    — register(type, 'schema', () => ({...})) — JSON Schema для UI
+  view.tsx      — register(type, 'react', Component) — React-рендеры
+  service.ts    — register(type, 'service', handler) — фоновый сервис
+```
+
+Регистрация:
+- Сервер: добавь импорт в `src/mods/index.ts`
+- Фронтенд: добавь импорт в `src/mods/views.ts` + `registerViews()`
+
+## Dev workflow
+
+```bash
+npm run schema        # извлечь JSON Schema из JSDoc → dist/schema/
+npm test              # tsx --test src/**/*.test.ts
+npm run dev:server    # tsx --watch src/server/index.ts (порт 3001)
+npm run dev:front     # vite (React-фронт)
+```
+
+Seed-данные: `data/base/` (git-tracked), runtime-данные: `data/work/` (gitignored).
+Overlay: work поверх base — записи идут в work, чтение fallback на base.

package/src/mod/docs/02-core-api.md

@@ -0,0 +1,68 @@
+# 02 — Core API
+
+## Типы
+
+```ts
+import {
+  type NodeData,        // { $path, $type, $rev?, $owner?, $acl?, ...components }
+  type ComponentData,    // { $type, $acl?, ...data }
+  type GroupPerm,        // { g: string, p: number }
+  type Ref,              // { $type: 'ref', $ref: string }
+  R, W, A, S,           // ACL bits: Read=1, Write=2, Admin=4, Subscribe=8
+} from '#core';
+```
+
+## Создание нод
+
+```ts
+import { createNode } from '#core';
+
+const node = createNode('/tasks/1', 'task', {
+  metadata: { $type: 'metadata', title: 'Hello' },
+  status:   { $type: 'status', value: 'draft' },
+});
+```
+
+## Работа с компонентами
+
+```ts
+import { getComponent, setComponent, removeComponent, getComponentsByType } from '#core';
+
+getComponent(node, 'metadata');              // → { $type, title } | undefined
+getComponentsByType(node, 'status');         // → [['status', { $type, value }]]
+setComponent(node, 'status', { $type: 'status', value: 'done' });
+removeComponent(node, 'status');             // → boolean
+```
+
+## Ссылки
+
+```ts
+import { ref, isRef } from '#core';
+import { resolveRef } from '#tree';
+
+const r = ref('/tasks/1');        // { $type: "ref", $ref: "/tasks/1" }
+isRef(r);                         // true
+const target = await resolveRef(store, refNode); // → NodeData
+```
+
+## Пути
+
+```ts
+import { dirname, basename, join, isChildPath } from '#core';
+
+dirname('/a/b');                  // → "/a"
+basename('/a/b');                 // → "b"
+join('/a', 'b');                  // → "/a/b"
+isChildPath('/a', '/a/b');        // → true (direct child)
+isChildPath('/a', '/a/b/c');      // → false (not direct)
+isChildPath('/a', '/a/b/c', false); // → true (any depth)
+```
+
+## Утилиты типов
+
+```ts
+import { isComponent, isOfType } from '#core';
+
+isComponent(value);               // value is ComponentData
+isOfType<T>(value, 'my-type');    // value is ComponentData<T>
+```

package/src/mod/docs/03-registry.md

@@ -0,0 +1,30 @@
+# 03 — Registry — система контекстов
+
+Единственный механизм расширения. `register(type, context, handler)` — привязать обработчик к типу в контексте.
+
+```ts
+import { register, resolve, render } from '#core';
+
+// Регистрация
+register('task', 'schema', () => ({ properties: { title: { type: 'string' } } }));
+register('task', 'react',  MyComponent);
+register('task', 'text',   (data) => `Task: ${data.title}`);
+
+// Резолв (fallback: exact → default@same-ctx → strip suffix → recurse → null)
+resolve('task', 'react:compact'); // → task@react:compact → default@react:compact → task@react → default@react → null
+
+// Рендер
+render(component, 'text');  // вызывает handler(component)
+```
+
+**Sealed registry:** дублирование `register()` молча игнорируется (HMR-safe). Переопределить нельзя. Расширяй через новые контексты (`react:mobile`), а не замену.
+
+## Introspection
+
+```ts
+import { getRegisteredTypes, getContextsForType, getMeta } from '#core';
+
+getRegisteredTypes('schema');        // → ['task', 'order', ...]
+getContextsForType('task');          // → ['schema', 'react', 'text', 'action:publish']
+getMeta('task', 'schema');           // → metadata объект или null
+```

package/src/mod/docs/04-store.md

@@ -0,0 +1,62 @@
+# 04 — Store — доступ к данным
+
+## Интерфейс
+
+```ts
+import { type Store, type Page, type ChildrenOpts } from '#tree';
+
+store.get(path);                                    // → NodeData | undefined
+store.set(node);                                    // upsert (OCC по $rev)
+store.remove(path);                                 // → boolean
+store.getChildren(path, { depth, limit, offset });  // → Page<NodeData>
+```
+
+`Page<T> = { items: T[], total: number }`
+
+## OCC (Optimistic Concurrency Control)
+
+Если нода имеет `$rev`, store.set() проверяет совпадение и бросает ошибку при конфликте:
+
+```ts
+const node = await store.get('/tasks/1');
+node.status.value = 'done';
+await store.set(node); // если $rev изменился — OptimisticConcurrencyError
+```
+
+## Реализации
+
+```ts
+import { createMemoryStore } from '#tree';
+import { createFsStore } from '#tree/fs';
+import { createMongoStore } from '#tree/mongo';
+
+const mem   = createMemoryStore();
+const fs    = await createFsStore('./data/base');
+const mongo = await createMongoStore(uri, 'mydb', 'nodes');
+```
+
+## Комбинаторы
+
+```ts
+import { createOverlayStore, createFilterStore } from '#tree';
+
+// Overlay: reads from upper first, writes go to upper only
+const overlay = createOverlayStore(workStore, baseStore);
+
+// Filter: routes set() по предикату (upper если true, lower если false)
+const filtered = createFilterStore(hotStore, coldStore, (node) => node.$type === 'hot');
+```
+
+## Query Store (sift)
+
+Виртуальная отфильтрованная проекция. Mongo-синтаксис через sift:
+
+```ts
+import { createQueryStore } from '#tree/query';
+
+const incoming = createQueryStore(
+  { source: '/orders/data', match: { status: { value: 'incoming' } } },
+  parentStore,
+);
+// getChildren('/') → только ноды, где status.value === 'incoming'
+```

package/src/mod/docs/05-comp.md

@@ -0,0 +1,111 @@
+# 05 — registerComp — типизированные компоненты
+
+Класс = схема полей + методы-экшены. Методы автоматически регистрируются как `action:{name}`.
+
+```ts
+import { registerComp, type CompClass } from '#comp';
+
+class Status {
+  value = 'draft';
+
+  publish() {
+    this.value = 'published';
+  }
+
+  archive() {
+    this.value = 'archived';
+  }
+}
+
+registerComp('order.status', Status);
+// Автоматически: register('order.status', 'action:publish', handler)
+//                register('order.status', 'action:archive', handler)
+```
+
+## getCtx() — доступ к Store из методов класса
+
+Методы класса получают `this` = Immer draft (компонент). Для доступа к store, ноде и AbortSignal используй `getCtx()`:
+
+```ts
+import { getCtx, registerComp } from '#comp';
+import { join, type NodeData } from '#core';
+
+class Portfolio {
+  risk = 0.5;
+
+  setRisk(data: { value: number }) {
+    this.risk = data.value;  // простая мутация — getCtx не нужен
+  }
+
+  async rebalance() {
+    const { node, store } = getCtx();
+    const { items } = await store.getChildren(join(node.$path, 'positions'));
+
+    for (const pos of items) {
+      await store.set(pos);
+    }
+
+    return { rebalanced: items.length };
+  }
+
+  async selfDestruct() {
+    const { node, store } = getCtx();
+    await store.remove(node.$path);
+  }
+}
+
+registerComp('portfolio', Portfolio);
+```
+
+**Как это работает:** перед вызовом метода система ставит контекст в глобальную переменную. JS однопоточный — между установкой и первой синхронной строкой метода ничто не вклинится, поэтому `getCtx()` всегда захватывает правильный контекст.
+
+**CompCtx:**
+```ts
+type CompCtx = {
+  node: NodeData;       // полная нода (Immer draft в executeAction)
+  store: Store;         // реактивный store
+  signal: AbortSignal;  // таймаут 30с
+};
+```
+
+**Правило:** если метод только мутирует `this` — getCtx не нужен. Если нужен store/node — `const ctx = getCtx()` на первой строке (до любого await).
+
+## Needs — зависимости от соседних компонентов
+
+```ts
+class PublishedDate {
+  date = '';
+
+  stamp(data: unknown, siblings: Record<string, ComponentData>) {
+    this.date = new Date().toISOString();
+  }
+}
+
+registerComp('published-date', PublishedDate, { needs: ['status'] });
+```
+
+## Type-safe доступ к компонентам
+
+```ts
+import { getComp, setComp, newComp, getCompField } from '#comp';
+
+const status = getComp(node, Status);           // → ComponentData<Status> | undefined
+setComp(node, Status, { value: 'done' });       // обновляет поля
+const fresh = newComp(Status, { value: 'new' }); // создаёт { $type: 'order.status', value: 'new' }
+
+const [fieldName, comp] = getCompField(node, Status)!; // → ['status', {...}]
+```
+
+## JSDoc → JSON Schema
+
+```ts
+class BlockHero {
+  /** @title Заголовок @description Главный заголовок страницы */
+  title = '';
+  /** @title Картинка @format image */
+  image = '';
+}
+
+registerComp('block.hero', BlockHero);
+// npm run schema → dist/schema/block.hero.json
+```

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.