@treenity/core 1.0.48 → 3.0.1

package/src/mod/examples/ticker/service.ts

@@ -0,0 +1,19 @@
+import { getComponent, type NodeData, register } from '#core';
+import { TickerConfig } from './types';
+
+register('ticker', 'service', async (node: NodeData, ctx) => {
+  const config = getComponent(node, TickerConfig);
+  const interval = (config?.intervalSec ?? 10) * 1000;
+
+  const timer = setInterval(async () => {
+    const price = 50000 + Math.random() * 1000; // stub — replace with real API
+    await ctx.store.set({
+      $path: `${node.$path}/${Date.now()}`,
+      $type: 'ticker.price',
+      price,
+      ts: Date.now(),
+    } as NodeData);
+  }, interval);
+
+  return { stop: async () => clearInterval(timer) };
+});

package/src/mod/examples/ticker/ticker.test.ts

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { TickerConfig } from './types';
+
+describe('TickerConfig', () => {
+  it('has sensible defaults', () => {
+    const c = new TickerConfig();
+    assert.equal(c.symbol, 'BTC');
+    assert.equal(c.intervalSec, 10);
+  });
+
+  it('configure updates fields', () => {
+    const c = new TickerConfig();
+    c.configure({ symbol: 'ETH', intervalSec: 30 });
+    assert.equal(c.symbol, 'ETH');
+    assert.equal(c.intervalSec, 30);
+  });
+});

package/src/mod/examples/ticker/types.ts

@@ -0,0 +1,22 @@
+// Example mod: Ticker — price feed with real-time updates
+import { registerType } from '#comp';
+
+/** Price feed config — trading symbol and polling interval */
+export class TickerConfig {
+  symbol = 'BTC';
+  intervalSec = 10;
+
+  /** @description Update symbol and polling interval */
+  configure(data: { symbol: string; intervalSec: number }) {
+    this.symbol = data.symbol;
+    this.intervalSec = data.intervalSec;
+  }
+}
+registerType('ticker.config', TickerConfig);
+
+/** Latest price snapshot — current price and timestamp */
+export class TickerPrice {
+  price = 0;
+  ts = 0;
+}
+registerType('ticker.price', TickerPrice);

package/src/mod/examples/ticker/view.tsx

@@ -0,0 +1,19 @@
+import { register } from '#core';
+import { useCurrentNode } from '@treenity/react/context';
+import { useChildren } from '@treenity/react/hooks';
+
+register('ticker', 'react', () => {
+  const node = useCurrentNode();
+  const prices = useChildren(node.$path, { limit: 20, watchNew: true });
+
+  return (
+    <div className="space-y-1 p-2">
+      <h3 className="font-bold">{node.$path}</h3>
+      {prices.map(p => (
+        <div key={p.$path} className="text-sm font-mono">
+          ${(p as any).price?.toFixed(2)} — {new Date((p as any).ts).toLocaleTimeString()}
+        </div>
+      ))}
+    </div>
+  );
+});

package/src/mod/index.ts

@@ -0,0 +1,12 @@
+// Treenity Module System — public API
+
+export { defineMod } from './types';
+export type { TreenityMod, ModManifest, ModState, LoadedMod } from './types';
+export { discoverMods } from './discover';
+export { sortByDependencies, loadMods, loadLocalMods, loadAllMods, getLoadedMods, getMod, isModLoaded, clearModRegistry } from './loader';
+export type { LoadTarget, LoadResult } from './loader';
+export { OptimisticBuffer } from './optimistic';
+export type { PendingMutation } from './optimistic';
+export { registerPrefab, getPrefab, getModPrefabs, getRegisteredMods, getSeedPrefabs, clearPrefabs } from './prefab';
+export type { PrefabSetup, PrefabMeta, PrefabEntry } from './prefab';
+export { getTypesForMod, inferModFromType, clearTracking } from './tracking';

package/src/mod/loader.test.ts

@@ -0,0 +1,220 @@
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { clearModRegistry, getLoadedMods, getMod, isModLoaded, loadLocalMods, loadMods, sortByDependencies } from './loader';
+import type { ModManifest } from './types';
+
+function m(name: string, deps?: string[]): ModManifest {
+  return { name, version: '1.0.0', dependencies: deps };
+}
+
+describe('sortByDependencies', () => {
+  it('returns mods in dependency order', () => {
+    const mods = [m('app', ['ui', 'auth']), m('auth', ['core']), m('ui', ['core']), m('core')];
+    const sorted = sortByDependencies(mods);
+    const names = sorted.map(m => m.name);
+
+    // core must come before auth and ui; auth and ui before app
+    assert.ok(names.indexOf('core') < names.indexOf('auth'));
+    assert.ok(names.indexOf('core') < names.indexOf('ui'));
+    assert.ok(names.indexOf('auth') < names.indexOf('app'));
+    assert.ok(names.indexOf('ui') < names.indexOf('app'));
+  });
+
+  it('handles no dependencies', () => {
+    const mods = [m('a'), m('b'), m('c')];
+    const sorted = sortByDependencies(mods);
+    assert.equal(sorted.length, 3);
+  });
+
+  it('throws on missing dependency', () => {
+    assert.throws(
+      () => sortByDependencies([m('app', ['ghost'])]),
+    );
+  });
+
+  it('throws on circular dependency (simple cycle)', () => {
+    assert.throws(
+      () => sortByDependencies([m('a', ['b']), m('b', ['a'])]),
+    );
+  });
+
+  it('throws on circular dependency (3-node cycle)', () => {
+    assert.throws(
+      () => sortByDependencies([m('a', ['b']), m('b', ['c']), m('c', ['a'])]),
+    );
+  });
+
+  it('handles diamond dependency (A→B,C; B→D; C→D)', () => {
+    const mods = [m('A', ['B', 'C']), m('B', ['D']), m('C', ['D']), m('D')];
+    const sorted = sortByDependencies(mods);
+    const names = sorted.map(m => m.name);
+
+    assert.ok(names.indexOf('D') < names.indexOf('B'));
+    assert.ok(names.indexOf('D') < names.indexOf('C'));
+    assert.ok(names.indexOf('B') < names.indexOf('A'));
+    assert.ok(names.indexOf('C') < names.indexOf('A'));
+  });
+
+  it('handles deep chain', () => {
+    const chain = Array.from({ length: 10 }, (_, i) => m(`m${i}`, i > 0 ? [`m${i - 1}`] : []));
+    const sorted = sortByDependencies(chain.reverse()); // reverse to make it harder
+    const names = sorted.map(m => m.name);
+
+    for (let i = 1; i < 10; i++) {
+      assert.ok(names.indexOf(`m${i - 1}`) < names.indexOf(`m${i}`),
+        `m${i - 1} should come before m${i}`);
+    }
+  });
+
+  it('handles single mod with self-dependency as circular', () => {
+    assert.throws(
+      () => sortByDependencies([m('narcissist', ['narcissist'])]),
+    );
+  });
+
+  it('detects partial cycle (some acyclic, some cyclic)', () => {
+    assert.throws(
+      () => sortByDependencies([m('ok'), m('a', ['b']), m('b', ['a'])]),
+    );
+  });
+});
+
+describe('loadMods', () => {
+  beforeEach(() => clearModRegistry());
+
+  it('loads mods without entry points (manifest-only)', async () => {
+    const result = await loadMods([m('simple')], 'server');
+    assert.deepEqual(result.loaded, ['simple']);
+    assert.deepEqual(result.failed, []);
+    assert.equal(isModLoaded('simple'), true);
+  });
+
+  it('tracks loaded mods in registry', async () => {
+    await loadMods([m('a'), m('b')], 'server');
+    assert.equal(getLoadedMods().length, 2);
+    assert.equal(getMod('a')?.state, 'loaded');
+    assert.equal(getMod('b')?.state, 'loaded');
+  });
+
+  it('fails if dependency not loaded', async () => {
+    const manifest: ModManifest = {
+      name: 'orphan',
+      version: '1.0.0',
+      dependencies: ['missing'],
+    };
+
+    // sortByDependencies will throw on unknown dep
+    await assert.rejects(
+      () => loadMods([manifest], 'server'),
+    );
+  });
+
+  it('fails gracefully on bad import path', async () => {
+    const manifest: ModManifest = {
+      name: 'bad-import',
+      version: '1.0.0',
+      server: './nonexistent.js',
+      packagePath: '/tmp/fake-package',
+    };
+
+    const result = await loadMods([manifest], 'server');
+    assert.equal(result.failed.length, 1);
+    assert.equal(result.failed[0].name, 'bad-import');
+    assert.equal(getMod('bad-import')?.state, 'failed');
+  });
+
+  it('clearModRegistry resets state', async () => {
+    await loadMods([m('x')], 'server');
+    assert.equal(getLoadedMods().length, 1);
+    clearModRegistry();
+    assert.equal(getLoadedMods().length, 0);
+    assert.equal(getMod('x'), undefined);
+  });
+
+  it('records loadedAt timestamp', async () => {
+    const before = Date.now();
+    await loadMods([m('timed')], 'server');
+    const after = Date.now();
+    const mod = getMod('timed')!;
+    assert.ok(mod.loadedAt! >= before && mod.loadedAt! <= after);
+  });
+
+  it('loads dependencies before dependents', async () => {
+    const order: string[] = [];
+
+    // We can't easily mock dynamic imports, but we can verify the sorted order
+    // by checking that dependencies resolve in order within the registry
+    const mods = [m('child', ['parent']), m('parent')];
+    await loadMods(mods, 'client');
+
+    const loaded = getLoadedMods();
+    const parentIdx = loaded.findIndex(m => m.manifest!.name === 'parent');
+    const childIdx = loaded.findIndex(m => m.manifest!.name === 'child');
+    assert.ok(parentIdx < childIdx, 'parent should load before child');
+  });
+
+  it('subsequent failed mod does not block already-loaded mods', async () => {
+    const mods: ModManifest[] = [
+      m('ok-mod'),
+      { name: 'fail-mod', version: '1.0.0', server: './nope.js', packagePath: '/bad' },
+    ];
+
+    const result = await loadMods(mods, 'server');
+    assert.equal(result.loaded.length, 1);
+    assert.equal(result.failed.length, 1);
+    assert.equal(isModLoaded('ok-mod'), true);
+    assert.equal(isModLoaded('fail-mod'), false);
+  });
+});
+
+describe('loadLocalMods', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    clearModRegistry();
+    tmpDir = mkdtempSync(join(tmpdir(), 'treenity-mods-'));
+  });
+
+  it('discovers mod with server.ts in a directory', async () => {
+    const modDir = join(tmpDir, 'my-mod');
+    mkdirSync(modDir);
+    writeFileSync(join(modDir, 'server.ts'), 'globalThis.__canary_server_loaded = true;');
+
+    const result = await loadLocalMods(tmpDir, 'server');
+    assert.deepEqual(result.loaded, ['my-mod']);
+    assert.equal(result.failed.length, 0);
+
+    rmSync(tmpDir, { recursive: true });
+  });
+
+  it('skips mod without matching entry file', async () => {
+    const modDir = join(tmpDir, 'server-only');
+    mkdirSync(modDir);
+    writeFileSync(join(modDir, 'server.ts'), '');
+
+    const result = await loadLocalMods(tmpDir, 'client');
+    assert.deepEqual(result.loaded, []);
+
+    rmSync(tmpDir, { recursive: true });
+  });
+
+  it('returns empty for nonexistent directory', async () => {
+    const result = await loadLocalMods('/tmp/no-such-dir-xyz-42', 'server');
+    assert.deepEqual(result.loaded, []);
+    assert.deepEqual(result.failed, []);
+  });
+
+  it('skips hidden directories', async () => {
+    const modDir = join(tmpDir, '.hidden-mod');
+    mkdirSync(modDir);
+    writeFileSync(join(modDir, 'server.ts'), '');
+
+    const result = await loadLocalMods(tmpDir, 'server');
+    assert.deepEqual(result.loaded, []);
+
+    rmSync(tmpDir, { recursive: true });
+  });
+});

package/src/mod/loader.ts

@@ -0,0 +1,207 @@
+// Treenity Module Loader — dependency sort, load, seed
+
+import type { Tree } from '#tree';
+import { readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { setCurrentMod } from './tracking';
+import type { LoadedMod, ModManifest, TreenityMod } from './types';
+
+// ── Dependency sorting (Kahn's algorithm) ──
+
+export function sortByDependencies(mods: ModManifest[]): ModManifest[] {
+  const byName = new Map(mods.map(m => [m.name, m]));
+  const inDegree = new Map<string, number>();
+  const adj = new Map<string, string[]>();
+
+  for (const m of mods) {
+    if (!inDegree.has(m.name)) inDegree.set(m.name, 0);
+    if (!adj.has(m.name)) adj.set(m.name, []);
+
+    for (const dep of m.dependencies ?? []) {
+      if (!byName.has(dep)) throw new Error(`Mod "${m.name}" depends on unknown mod "${dep}"`);
+      if (!adj.has(dep)) adj.set(dep, []);
+      adj.get(dep)!.push(m.name);
+      inDegree.set(m.name, (inDegree.get(m.name) ?? 0) + 1);
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [name, deg] of inDegree) {
+    if (deg === 0) queue.push(name);
+  }
+
+  const sorted: ModManifest[] = [];
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    sorted.push(byName.get(name)!);
+    for (const next of adj.get(name) ?? []) {
+      const deg = inDegree.get(next)! - 1;
+      inDegree.set(next, deg);
+      if (deg === 0) queue.push(next);
+    }
+  }
+
+  if (sorted.length !== mods.length) {
+    const stuck = mods.filter(m => !sorted.includes(m)).map(m => m.name);
+    throw new Error(`Circular dependency among mods: ${stuck.join(', ')}`);
+  }
+
+  return sorted;
+}
+
+// ── Registry of loaded mods ──
+
+const loaded = new Map<string, LoadedMod>();
+
+export function getLoadedMods(): LoadedMod[] {
+  return [...loaded.values()];
+}
+
+export function getMod(name: string): LoadedMod | undefined {
+  return loaded.get(name);
+}
+
+export function isModLoaded(name: string): boolean {
+  return loaded.get(name)?.state === 'loaded';
+}
+
+export function clearModRegistry(): void {
+  loaded.clear();
+}
+
+// ── Loader ──
+
+export type LoadTarget = 'server' | 'client';
+
+export interface LoadResult {
+  loaded: string[];
+  failed: { name: string; error: Error }[];
+}
+
+export async function loadMods(
+  manifests: ModManifest[],
+  target: LoadTarget,
+  store?: Tree,
+): Promise<LoadResult> {
+  const sorted = sortByDependencies(manifests);
+  const result: LoadResult = { loaded: [], failed: [] };
+
+  for (const manifest of sorted) {
+    const entry: LoadedMod = { name: manifest.name, manifest, state: 'loading' };
+    loaded.set(manifest.name, entry);
+
+    try {
+      for (const dep of manifest.dependencies ?? []) {
+        if (!isModLoaded(dep)) throw new Error(`Dependency "${dep}" not loaded`);
+      }
+
+      const entryPath = target === 'server' ? manifest.server : manifest.client;
+      let mod: TreenityMod | undefined;
+
+      if (entryPath && manifest.packagePath) {
+        const fullPath = join(manifest.packagePath, entryPath);
+        setCurrentMod(manifest.name);
+        const exported = await import(fullPath);
+        setCurrentMod(null);
+        mod = exported.default as TreenityMod;
+      }
+
+      if (mod?.onLoad) await mod.onLoad();
+
+      // Seed (server-only, needs store)
+      if (target === 'server' && store) {
+        if (mod?.seed) {
+          await mod.seed(store);
+        } else if (manifest.seed && manifest.packagePath) {
+          const seedMod = await import(join(manifest.packagePath, manifest.seed));
+          await seedMod.default(store);
+        }
+      }
+
+      entry.mod = mod;
+      entry.state = 'loaded';
+      entry.loadedAt = Date.now();
+      result.loaded.push(manifest.name);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      entry.state = 'failed';
+      entry.error = error;
+      result.failed.push({ name: manifest.name, error });
+    }
+  }
+
+  return result;
+}
+
+// ── Local mod loader (side-effect imports from src/mods/) ──
+
+export async function loadLocalMods(modsDir: string, target: LoadTarget): Promise<LoadResult> {
+  const result: LoadResult = { loaded: [], failed: [] };
+  const entryFile = target === 'server' ? 'server.ts' : 'client.ts';
+  let entries: import('node:fs').Dirent[];
+
+  try {
+    entries = await readdir(modsDir, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+
+    const filePath = join(modsDir, entry.name, entryFile);
+    try { await stat(filePath); } catch { continue; }
+
+    const modEntry: LoadedMod = { name: entry.name, state: 'loading' };
+    loaded.set(entry.name, modEntry);
+
+    try {
+      setCurrentMod(entry.name);
+      await import(filePath);
+      setCurrentMod(null);
+      modEntry.state = 'loaded';
+      modEntry.loadedAt = Date.now();
+      result.loaded.push(entry.name);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      modEntry.state = 'failed';
+      modEntry.error = error;
+      result.failed.push({ name: entry.name, error });
+    }
+  }
+
+  return result;
+}
+
+// ── Load all mods: internal + engine + project (CWD) ──
+
+export async function loadAllMods(target: LoadTarget, ...extraDirs: string[]): Promise<LoadResult> {
+  const internalDir = new URL('../mods', import.meta.url).pathname;
+  const engineDir = new URL('../../../mods', import.meta.url).pathname;
+
+  const dirs = [internalDir, engineDir];
+
+  // CWD/mods/ if different from engine mods
+  const projectDir = resolve('mods');
+  if (resolve(projectDir) !== resolve(engineDir)) dirs.push(projectDir);
+
+  dirs.push(...extraDirs);
+
+  const seen = new Set<string>();
+  const result: LoadResult = { loaded: [], failed: [] };
+
+  for (const dir of dirs) {
+    const abs = resolve(dir);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+
+    const r = await loadLocalMods(dir, target);
+    result.loaded.push(...r.loaded);
+    result.failed.push(...r.failed);
+  }
+
+  if (result.failed.length) console.error('failed mods:', result.failed.map(f => `${f.name}: ${f.error.message}`).join(', '));
+  console.log(`mods: ${result.loaded.join(', ')}`);
+
+  return result;
+}