@treenity/core 1.0.48 → 3.0.1

package/src/mod/discover.test.ts

@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { discoverMods } from './discover';
+
+let tmp: string;
+
+async function makePkg(dir: string, pkg: Record<string, unknown>) {
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, 'package.json'), JSON.stringify(pkg));
+}
+
+describe('discoverMods', () => {
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), 'treenity-discover-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('finds packages with "treenity" field', async () => {
+    await makePkg(join(tmp, 'treenity-mod-weather'), {
+      name: 'treenity-mod-weather',
+      version: '1.2.3',
+      treenity: {
+        name: 'weather',
+        types: ['weather.sensor', 'weather.config'],
+        server: './dist/server.js',
+        client: './dist/client.js',
+      },
+    });
+
+    const mods = await discoverMods(tmp);
+    assert.equal(mods.length, 1);
+    assert.equal(mods[0].name, 'weather');
+    assert.equal(mods[0].version, '1.2.3');
+    assert.deepEqual(mods[0].types, ['weather.sensor', 'weather.config']);
+    assert.equal(mods[0].server, './dist/server.js');
+    assert.equal(mods[0].packagePath, join(tmp, 'treenity-mod-weather'));
+  });
+
+  it('ignores packages without "treenity" field', async () => {
+    await makePkg(join(tmp, 'express'), { name: 'express', version: '4.0.0' });
+    await makePkg(join(tmp, 'treenity-mod-foo'), {
+      name: 'treenity-mod-foo',
+      treenity: { name: 'foo' },
+    });
+
+    const mods = await discoverMods(tmp);
+    assert.equal(mods.length, 1);
+    assert.equal(mods[0].name, 'foo');
+  });
+
+  it('discovers scoped packages (@scope/pkg)', async () => {
+    await makePkg(join(tmp, '@myorg', 'treenity-mod-billing'), {
+      name: '@myorg/treenity-mod-billing',
+      version: '2.0.0',
+      treenity: { name: 'billing', dependencies: ['auth'] },
+    });
+
+    const mods = await discoverMods(tmp);
+    assert.equal(mods.length, 1);
+    assert.equal(mods[0].name, 'billing');
+    assert.deepEqual(mods[0].dependencies, ['auth']);
+  });
+
+  it('handles multiple mods including mixed scoped/unscoped', async () => {
+    await makePkg(join(tmp, 'treenity-mod-a'), { name: 'a', treenity: { name: 'alpha' } });
+    await makePkg(join(tmp, '@org', 'mod-b'), { name: 'b', treenity: { name: 'beta' } });
+    await makePkg(join(tmp, 'lodash'), { name: 'lodash' });
+    await makePkg(join(tmp, '@org', 'other'), { name: 'other' });
+
+    const mods = await discoverMods(tmp);
+    assert.equal(mods.length, 2);
+    const names = mods.map(m => m.name).sort();
+    assert.deepEqual(names, ['alpha', 'beta']);
+  });
+
+  it('returns empty array for nonexistent directory', async () => {
+    const mods = await discoverMods('/nonexistent/path/12345');
+    assert.deepEqual(mods, []);
+  });
+
+  it('skips packages with malformed package.json', async () => {
+    await mkdir(join(tmp, 'broken-mod'), { recursive: true });
+    await writeFile(join(tmp, 'broken-mod', 'package.json'), 'NOT JSON{{{');
+    await makePkg(join(tmp, 'good-mod'), { name: 'g', treenity: { name: 'good' } });
+
+    const mods = await discoverMods(tmp);
+    assert.equal(mods.length, 1);
+    assert.equal(mods[0].name, 'good');
+  });
+
+  it('skips dot-directories', async () => {
+    await makePkg(join(tmp, '.cache'), { name: 'cache', treenity: { name: 'cache' } });
+    const mods = await discoverMods(tmp);
+    assert.equal(mods.length, 0);
+  });
+
+  it('falls back to pkg.name and pkg.version when treenity field is minimal', async () => {
+    await makePkg(join(tmp, 'treenity-mod-simple'), {
+      name: '@scope/treenity-mod-simple',
+      version: '3.0.0',
+      treenity: {},
+    });
+
+    const mods = await discoverMods(tmp);
+    assert.equal(mods.length, 1);
+    assert.equal(mods[0].name, '@scope/treenity-mod-simple');
+    assert.equal(mods[0].version, '3.0.0');
+  });
+
+  it('handles missing version gracefully', async () => {
+    await makePkg(join(tmp, 'mod-no-ver'), {
+      name: 'mod-no-ver',
+      treenity: { name: 'no-ver' },
+    });
+
+    const mods = await discoverMods(tmp);
+    assert.equal(mods[0].version, '0.0.0');
+  });
+
+  it('handles packages with no package.json at all', async () => {
+    await mkdir(join(tmp, 'empty-dir'), { recursive: true });
+    await makePkg(join(tmp, 'real-mod'), { name: 'r', treenity: { name: 'real' } });
+
+    const mods = await discoverMods(tmp);
+    assert.equal(mods.length, 1);
+  });
+});

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
+```