@treenity/core 1.0.48 → 3.0.1

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<T = any> {
+}
+
+export type ContextHandler<C extends string, T = any> = C extends keyof ContextHandlers<T>
+  ? ContextHandlers<T>[C]
+  : C extends `${infer Base}:${string}`
+    ? ContextHandler<Base, T>
+    : Handler;

package/src/core/index.test.ts

@@ -0,0 +1,224 @@
+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';
+import { registerBuiltins } from '#mods/treenity/builtins';
+
+const testTypes = ['test.doc', 'test.item', 'test.session', 'test.task'];
+
+export function registerTestTypes() {
+  for (const t of testTypes)
+    register(t, 'schema', () => ({ $id: t, type: 'object' as const, title: t, properties: {} }));
+}
+
+registerTestTypes();
+
+export function clearRegistry(): void {
+  mapRegistry((t, c) => unregister(t, c));
+  registerBuiltins();
+  registerTestTypes();
+}
+
+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 as any)['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);
+  });
+
+  // Regression: /board must not match /boards (prefix overlap without separator)
+  it('isChildPath rejects prefix overlap without separator', () => {
+    assert.equal(isChildPath('/board', '/boards'), false);
+    assert.equal(isChildPath('/board', '/boards/test'), false);
+    assert.equal(isChildPath('/board', '/boards/test', false), false);
+    assert.equal(isChildPath('/board', '/board/real'), true);
+    assert.equal(isChildPath('/board', '/board/real/deep', 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,38 @@
+// ── 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 === parent) return false;
+  // Must match parent + '/' to avoid /board matching /boards
+  const prefix = parent === '/' ? '/' : parent + '/';
+  if (!candidate.startsWith(prefix)) return false;
+  if (directOnly) {
+    const rest = candidate.slice(prefix.length);
+    return rest.length > 0 && !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,112 @@
+import { type Class, 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;
+export function register<T, C extends string>(type: Class<T>, context: C, handler: ContextHandler<C, T>, meta?: Record<string, unknown>): void;
+export function register(type: TypeId, context: string, handler: Handler, 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';

package/src/index.ts

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

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,199 @@
+// Unified logging: tree-persisted nodes + ring buffer fallback + debug filter + console intercept
+
+import dayjs from 'dayjs'
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+export interface LogEntry {
+  t: number
+  level: LogLevel
+  msg: string
+  code?: string
+  sub?: string
+  userId?: string
+  method?: string
+  path?: string
+}
+
+// ── Execution context provider — set by comp/index.ts to avoid circular imports ──
+
+type CtxProvider = () => Record<string, unknown> | null
+let _getCtx: CtxProvider = () => null
+
+export function setCtxProvider(fn: CtxProvider) { _getCtx = fn }
+
+// ── Log listeners ──
+
+type OnLog = (entry: LogEntry) => void
+const listeners: OnLog[] = []
+
+export function addOnLog(fn: OnLog) { listeners.push(fn) }
+
+// ── Timestamp ID: YYMMDD-HHmmss-mmm-NNN ──
+
+let lastMs = 0
+let seq = 0
+
+export function makeLogPath(): string {
+  const now = Date.now()
+  if (now === lastMs) {
+    seq++
+  } else {
+    lastMs = now
+    seq = 0
+  }
+
+  const stamp = dayjs(now).format('YYMMDD-HHmmss-SSS')
+  const sq = String(seq).padStart(3, '0')
+
+  return `/sys/logs/${stamp}-${sq}`
+}
+
+function notify(entry: LogEntry) {
+  for (const fn of listeners) fn(entry)
+}
+
+// ── Ring buffer (fallback before tree init) ──
+
+const MAX = 2000
+const buffer: LogEntry[] = []
+let cursor = 0
+let total = 0
+
+function push(level: LogLevel, args: unknown[]) {
+  // Extract [tag] → sub
+  let sub: string | undefined
+  if (typeof args[0] === 'string') {
+    const m = args[0].match(/^\[([^\]]+)\]$/)
+    if (m) {
+      sub = m[1]
+      args = args.slice(1)
+    }
+  }
+
+  // Extract UPPER_SNAKE code
+  let code: string | undefined
+  if (args.length > 1 && typeof args[0] === 'string' && /^[A-Z][A-Z0-9_]+$/.test(args[0])) {
+    code = args[0]
+    args = args.slice(1)
+  }
+
+  const msg = args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ')
+  const ctx = _getCtx()
+
+  const entry: LogEntry = {
+    t: Date.now(),
+    level,
+    msg,
+    code,
+    sub,
+    userId: ctx?.userId as string | undefined,
+    method: ctx?.method as string | undefined,
+    path: ctx?.path as string | undefined,
+  }
+
+  if (listeners.length) {
+    notify(entry)
+  } else {
+    if (total < MAX) {
+      buffer.push(entry)
+    } else {
+      buffer[cursor] = entry
+    }
+    cursor = (cursor + 1) % MAX
+    total++
+  }
+}
+
+/** Get ordered log entries from ring buffer (oldest first) */
+function getOrdered(): LogEntry[] {
+  if (total <= MAX) return buffer.slice()
+  return [...buffer.slice(cursor), ...buffer.slice(0, cursor)]
+}
+
+// ── Query (ring buffer fallback — when tree available, use sift via getChildren) ──
+
+export interface LogQuery {
+  grep?: string
+  level?: LogLevel | LogLevel[]
+  head?: number
+  tail?: number
+}
+
+export function queryLogs(opts: LogQuery = {}): LogEntry[] {
+  let entries = getOrdered()
+
+  if (opts.level) {
+    const levels = Array.isArray(opts.level) ? opts.level : [opts.level]
+    entries = entries.filter(e => levels.includes(e.level))
+  }
+
+  if (opts.grep) {
+    const re = new RegExp(opts.grep, 'i')
+    entries = entries.filter(e => re.test(e.msg))
+  }
+
+  if (opts.tail) entries = entries.slice(-opts.tail)
+  if (opts.head) entries = entries.slice(0, opts.head)
+
+  return entries
+}
+
+export function logStats() {
+  return { buffered: Math.min(total, MAX), total, max: MAX }
+}
+
+// ── Debug filter ──
+
+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 Record<string, unknown>).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) },
+  }
+}
+
+// ── Console intercept — call once at startup ──
+
+let intercepted = false
+
+export function interceptConsole() {
+  if (intercepted) return
+  intercepted = true
+
+  for (const level of ['debug', 'info', 'warn', 'error'] as const) {
+    const orig = console[level]
+    console[level] = (...args: unknown[]) => {
+      push(level, args)
+      orig.apply(console, args)
+    }
+  }
+
+  // console.log → info level
+  const origLog = console.log
+  console.log = (...args: unknown[]) => {
+    push('info', args)
+    origLog.apply(console, args)
+  }
+}