@treenity/core 1.0.48 → 3.0.0

package/src/core/context.ts

@@ -0,0 +1,14 @@
+// ── Context ──
+
+export type Handler = (...args: any[]) => any;
+
+// Typed context handlers — augmented by layers via declaration merging
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ContextHandlers {
+}
+
+export type ContextHandler<C extends string> = C extends keyof ContextHandlers
+  ? ContextHandlers[C]
+  : C extends `${infer Base}:${string}`
+    ? ContextHandler<Base>
+    : Handler;

package/src/core/index.test.ts

@@ -0,0 +1,203 @@
+import { basename, dirname, isChildPath, join } from '#core/path';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  createNode,
+  getComponent,
+  getComponents,
+  isComponent,
+  isRef,
+  mapRegistry,
+  ref,
+  register,
+  removeComponent,
+  render,
+  resolve,
+  unregister,
+} from './index';
+
+export function clearRegistry(): void {
+  mapRegistry((t, c) => unregister(t, c));
+}
+
+describe('Node', () => {
+  it('creates with type and path', () => {
+    const node = createNode('/tasks/1', 'task');
+    assert.equal(node.$path, '/tasks/1');
+    assert.equal(node.$type, 't.task');
+  });
+
+  it('creates with components', () => {
+    const node = createNode('/tasks/1', 'task', {}, {
+      info: { $type: 'task', status: 'open' },
+      budget: { $type: 'money', amount: 100, currency: 'USD' },
+    });
+    assert.equal(node.info.$type, 'task');
+    assert.equal(node.budget.amount, 100);
+  });
+
+  it('rejects $ prefix in component names', () => {
+    assert.throws(() => createNode('/x', 'x', {}, { $bad: { $type: 'x' } }));
+  });
+});
+
+describe('Component access', () => {
+  const node = createNode('/tasks/1', 'task', {}, {
+    budget: { $type: 'money', amount: 100, currency: 'USD' },
+    estimate: { $type: 'money', amount: 200, currency: 'USD' },
+  });
+
+  it('get by type — node-level match', () => {
+    // node.$type is 't.task', getComponent('task') normalizes and matches
+    const comp = getComponent(node, 'task');
+    assert.equal(comp, node);
+  });
+
+  it('get by type — named component', () => {
+    const comp = getComponent(node, 'money');
+    assert.ok(comp);
+    assert.equal((comp as any).amount, 100); // first match: budget
+  });
+
+  it('get by type with field filter', () => {
+    const comp = getComponent(node, 'money', 'estimate');
+    assert.ok(comp);
+    assert.equal((comp as any).amount, 200);
+  });
+
+  it('returns undefined for missing type', () => {
+    assert.equal(getComponent(node, 'nope'), undefined);
+  });
+
+  it('returns undefined for wrong type at field', () => {
+    assert.equal(getComponent(node, 'task', 'budget'), undefined);
+  });
+
+  it('find all by type', () => {
+    const moneys = getComponents(node, 'money');
+    assert.equal(moneys.length, 2);
+    assert.deepEqual(moneys.map(([name]) => name).sort(), ['budget', 'estimate']);
+  });
+
+  it('isComponent type guard', () => {
+    assert.ok(isComponent(node['budget']));
+    assert.ok(!isComponent(node['missing']));
+    assert.ok(!isComponent('string'));
+    assert.ok(!isComponent(null));
+  });
+
+  it('set and remove', () => {
+    const n = createNode('/x', 'x');
+    (n as any).tag = { $type: 'tag', value: 'urgent' };
+    assert.ok(getComponent(n, 'tag'));
+    assert.equal(removeComponent(n, 'tag'), true);
+    assert.equal(getComponent(n, 'tag'), undefined);
+    assert.equal(removeComponent(n, 'tag'), false);
+  });
+});
+
+describe('Ref', () => {
+  it('creates ref', () => {
+    const r = ref('/users/bob');
+    assert.equal(r.$type, 'ref');
+    assert.equal(r.$ref, '/users/bob');
+  });
+
+  it('detects ref', () => {
+    assert.equal(isRef(ref('/x')), true);
+    assert.equal(isRef({ $type: 'task' }), false);
+    assert.equal(isRef(null), false);
+    assert.equal(isRef('string'), false);
+  });
+});
+
+describe('Path utils', () => {
+  it('parentPath', () => {
+    assert.equal(dirname('/'), null);
+    assert.equal(dirname('/tasks'), '/');
+    assert.equal(dirname('/tasks/123'), '/tasks');
+    assert.equal(dirname('/a/b/c'), '/a/b');
+  });
+
+  it('nodeName', () => {
+    assert.equal(basename('/tasks/123'), '123');
+    assert.equal(basename('/tasks'), 'tasks');
+  });
+
+  it('childPath', () => {
+    assert.equal(join('/', 'tasks'), '/tasks');
+    assert.equal(join('/tasks', '123'), '/tasks/123');
+  });
+
+  it('isChildPath direct', () => {
+    assert.equal(isChildPath('/tasks', '/tasks/123'), true);
+    assert.equal(isChildPath('/tasks', '/tasks/123/sub'), false);
+    assert.equal(isChildPath('/tasks', '/tasks'), false);
+    assert.equal(isChildPath('/', '/tasks'), true);
+    assert.equal(isChildPath('/', '/tasks/123'), false);
+  });
+
+  it('isChildPath recursive', () => {
+    assert.equal(isChildPath('/tasks', '/tasks/123/sub', false), true);
+    assert.equal(isChildPath('/', '/tasks/123', false), true);
+  });
+});
+
+describe('Context', () => {
+  it('register and resolve exact', () => {
+    clearRegistry();
+    register('task', 'test', (data) => `<Task ${(data as any).status} />`);
+    const handler = resolve('task', 'test');
+    assert.ok(handler);
+    assert.equal(handler({ $type: 'task', status: 'open' }), '<Task open />');
+  });
+
+  it('fallback from specific to general', () => {
+    clearRegistry();
+    register('task', 'test', () => 'general');
+    register('task', 'test:compact', () => 'compact');
+
+    assert.equal(resolve('task', 'test:compact')?.({} as any), 'compact');
+    assert.equal(resolve('task', 'test:compact:mini')?.({} as any), 'compact');
+    assert.equal(resolve('task', 'test')?.({} as any), 'general');
+  });
+
+  it('default wins over stripped context', () => {
+    clearRegistry();
+    register('default', 'test:compact:mini', () => 'default:mini');
+    register('default', 'test', () => 'default');
+    register('task', 'test', () => 'general');
+    register('task', 'test:compact', () => 'compact');
+
+    assert.equal(resolve('task', 'test:compact')?.({} as any), 'compact');
+    assert.equal(resolve('task', 'test:compact:mini')?.({} as any), 'default:mini');
+    assert.equal(resolve('task', 'test')?.({} as any), 'general');
+    assert.equal(resolve('unknown', 'test:compact:mini')?.({} as any), 'default:mini');
+    assert.equal(resolve('unknown', 'test:compact')?.({} as any), 'default');
+  });
+
+  it('fallback to default', () => {
+    clearRegistry();
+    register('default', 'test', () => 'default');
+    assert.equal(resolve('task', 'test')?.({} as any), 'default');
+    assert.equal(resolve('task', 'test:compact')?.({} as any), 'default');
+  });
+
+  it('strip still works without default', () => {
+    clearRegistry();
+    register('task', 'react', () => 'react');
+    assert.equal(resolve('task', 'react:edit:inline')?.({} as any), 'react');
+    assert.equal(resolve('task', 'react:edit')?.({} as any), 'react');
+  });
+
+  it('returns null when nothing found', () => {
+    clearRegistry();
+    assert.equal(resolve('unknown', 'test'), null);
+  });
+
+  it('render throws on missing handler', () => {
+    clearRegistry();
+    assert.throws(() => render({ $type: 'nope' }, 'react'));
+  });
+});
+

package/src/core/index.ts

@@ -0,0 +1,9 @@
+// Treenity Core — Layer 0
+// Node + Component + Context + Ref
+// Zero dependencies. < 500 lines.
+
+export * from './component';
+export * from './context';
+export * from './path';
+export * from './registry';
+

package/src/core/path.ts

@@ -0,0 +1,35 @@
+// ── Path utils ──
+
+export function dirname(path: string): string | null {
+  if (path === '/') return null;
+  const idx = path.lastIndexOf('/');
+  if (idx <= 0) return '/';
+  return path.slice(0, idx);
+}
+
+export function basename(path: string): string {
+  const idx = path.lastIndexOf('/');
+  return idx === -1 ? path : path.slice(idx + 1);
+}
+
+export function join(parent: string, name: string): string {
+  return parent === '/' ? `/${name}` : `${parent}/${name}`;
+}
+
+export function isChildPath(parent: string, candidate: string, directOnly = true): boolean {
+  if (!candidate.startsWith(parent) || candidate === parent) return false;
+  if (directOnly) {
+    const rest = parent === '/' ? candidate.slice(1) : candidate.slice(parent.length + 1);
+    return !rest.includes('/');
+  }
+
+  return true;
+}
+
+/** Validate a tree path — rejects traversal, double-slash, null bytes */
+export function assertSafePath(path: string): void {
+  if (!path.startsWith('/')) throw new Error(`Invalid path: must start with /`);
+  if (path.includes('\0')) throw new Error(`Invalid path: null byte`);
+  if (path.includes('//')) throw new Error(`Invalid path: double slash`);
+  if (path.split('/').some(s => s === '..')) throw new Error(`Invalid path: traversal`);
+}

package/src/core/registry.ts

@@ -0,0 +1,115 @@
+import { ComponentData, normalizeType, type TypeId } from './component';
+import { ContextHandler, Handler } from './context';
+
+const registry = new Map<string, Handler>();
+const metaRegistry = new Map<string, Record<string, unknown>>();
+
+// ── Registry subscription — lets React re-render when handlers change ──
+let version = 0;
+const listeners = new Set<() => void>();
+function bump() {
+  version++;
+  listeners.forEach(cb => cb());
+}
+export function subscribeRegistry(cb: () => void) {
+  listeners.add(cb);
+  return () => { listeners.delete(cb); };
+}
+export function getRegistryVersion() { return version; }
+
+function key(type: string, context: string): string {
+  return `${type}@${context}`;
+}
+
+export function register<C extends string>(
+  type: string,
+  context: C,
+  handler: ContextHandler<C>,
+  meta?: Record<string, unknown>,
+): void {
+  const k = key(normalizeType(type), context);
+  // Sealed: no overrides. In dev (HMR) modules re-execute, so we allow silent replace.
+  // In production, duplicate register = bug, caught by tests.
+  if (registry.has(k)) return;
+  registry.set(k, handler as Handler);
+  if (meta) metaRegistry.set(k, meta);
+  bump();
+}
+
+export function getMeta(type: TypeId, context: string): Record<string, unknown> | null {
+  return metaRegistry.get(key(normalizeType(type), context)) ?? null;
+}
+
+export function resolve<C extends string>(type: TypeId, context: C, _notifyMiss = true): ContextHandler<C> | null {
+  const n = normalizeType(type);
+  const exact = registry.get(key(n, context));
+  if (exact) return exact as ContextHandler<C>;
+
+  // Notify miss BEFORE default fallback — async loaders (UIX) start fetching,
+  // register when done, bump triggers re-render → next resolve finds exact match
+  if (_notifyMiss) missResolvers.get(context)?.(n);
+
+  const def = registry.get(key(normalizeType('default'), context));
+  if (def) return def as ContextHandler<C>;
+
+  // fallback: strip last segment ("react:compact" → "react")
+  const sep = context.lastIndexOf(':');
+  if (sep > 0) return resolve(type, context.slice(0, sep) as C, false);
+
+  return null;
+}
+
+// Returns the exact registered handler, no fallback, no miss notification
+export function resolveExact<C extends string>(type: TypeId, context: C): ContextHandler<C> | null {
+  return (registry.get(key(normalizeType(type), context)) ?? null) as ContextHandler<C> | null;
+}
+
+export function hasMissResolver(context: string): boolean {
+  return missResolvers.has(context);
+}
+
+export function unregister(type: string, context: string): boolean {
+  const k = key(normalizeType(type), context);
+  metaRegistry.delete(k);
+  const deleted = registry.delete(k);
+  if (deleted) bump();
+  return deleted;
+}
+
+export function mapRegistry<T>(fn: (type: string, context: string) => T | undefined): T[] {
+  const result: T[] = [];
+  for (const k of registry.keys()) {
+    const i = k.lastIndexOf('@');
+    const v = fn(k.slice(0, i), k.slice(i + 1));
+    if (v !== undefined) result.push(v);
+  }
+  return result;
+}
+
+export function getRegisteredTypes(context?: string): string[] {
+  return context
+    ? mapRegistry((t, c) => c === context ? t : undefined)
+    : [...new Set(mapRegistry(t => t))];
+}
+
+export function getContextsForType(type: TypeId): string[] {
+  const n = normalizeType(type);
+  return mapRegistry((t, c) => t === n ? c : undefined);
+}
+
+// ── Resolve miss — per-context extension point for dynamic loaders ──
+// One resolver per context. UIX uses this for 'react' to lazy-load views from type nodes.
+// REVIEW: if more per-context behavior emerges (validate, wrap, fallback), consider
+// evolving into defineContext('react', { onMiss, validate, ... }) trait system.
+const missResolvers = new Map<string, (type: string) => void>();
+export function onResolveMiss(context: string, resolver: (type: string) => void) {
+  missResolvers.set(context, resolver);
+}
+
+// ── Render (context-aware) ──
+
+export function render(data: ComponentData, context: string, ...args: unknown[]): unknown {
+  const handler = resolve(data.$type, context);
+  if (!handler) throw new Error(`No handler for type "${data.$type}" in context "${context}"`);
+  return handler(data, ...args);
+}

package/src/core.ts

@@ -0,0 +1 @@
+export * from './core/index.ts';

package/src/log.test.ts

@@ -0,0 +1,70 @@
+import assert from 'node:assert';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { createLogger, setDebug } from './log.js';
+
+describe('createLogger', () => {
+  const calls: { method: string; args: unknown[] }[] = []
+  const originals = { debug: console.debug, info: console.info, warn: console.warn, error: console.error }
+
+  beforeEach(() => {
+    calls.length = 0
+    for (const m of ['debug', 'info', 'warn', 'error'] as const) {
+      (console as any)[m] = (...args: unknown[]) => calls.push({ method: m, args })
+    }
+  })
+
+  afterEach(() => {
+    Object.assign(console, originals)
+    setDebug('')
+  })
+
+  it('info/warn/error always log with tag', () => {
+    const log = createLogger('test')
+    log.info('hello')
+    log.warn('careful')
+    log.error('boom')
+
+    assert.equal(calls.length, 3)
+    assert.deepStrictEqual(calls[0], { method: 'info', args: ['[test]', 'hello'] })
+    assert.deepStrictEqual(calls[1], { method: 'warn', args: ['[test]', 'careful'] })
+    assert.deepStrictEqual(calls[2], { method: 'error', args: ['[test]', 'boom'] })
+  })
+
+  it('debug is silent by default', () => {
+    const log = createLogger('test')
+    log.debug('hidden')
+    assert.equal(calls.length, 0)
+  })
+
+  it('setDebug enables debug for specific name', () => {
+    setDebug('foo')
+    const foo = createLogger('foo')
+    const bar = createLogger('bar')
+
+    foo.debug('visible')
+    bar.debug('hidden')
+
+    assert.equal(calls.length, 1)
+    assert.deepStrictEqual(calls[0], { method: 'debug', args: ['[foo]', 'visible'] })
+  })
+
+  it('setDebug("*") enables all', () => {
+    setDebug('*')
+    const log = createLogger('anything')
+    log.debug('visible')
+    assert.equal(calls.length, 1)
+  })
+
+  it('setDebug with comma-separated names', () => {
+    setDebug('a, b')
+    const a = createLogger('a')
+    const b = createLogger('b')
+    const c = createLogger('c')
+
+    a.debug('yes')
+    b.debug('yes')
+    c.debug('no')
+
+    assert.equal(calls.length, 2)
+  })
+})

package/src/log.ts

@@ -0,0 +1,28 @@
+const enabled = new Set<string>()
+let all = false
+
+export function setDebug(filter: string) {
+  enabled.clear()
+  all = false
+  if (filter === '*') { all = true; return }
+  for (const s of filter.split(',')) {
+    const t = s.trim()
+    if (t) enabled.add(t)
+  }
+}
+
+if (typeof process !== 'undefined' && process.env?.DEBUG) {
+  setDebug(process.env.DEBUG)
+}
+
+;(globalThis as any).setDebug = setDebug
+
+export function createLogger(name: string) {
+  const tag = `[${name}]`
+  return {
+    debug(...args: unknown[]) { if (all || enabled.has(name)) console.debug(tag, ...args) },
+    info(...args: unknown[]) { console.info(tag, ...args) },
+    warn(...args: unknown[]) { console.warn(tag, ...args) },
+    error(...args: unknown[]) { console.error(tag, ...args) },
+  }
+}

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);
+  });
+});