@treenity/core 1.0.48 → 3.0.0

package/src/server/mount.ts

@@ -0,0 +1,208 @@
+// Treenity Mount — Layer 4
+// Mount = component on node. Adapter resolved via context system.
+// Core untouched. Tree interface preserved.
+
+import { isComponent, isRef, type NodeData, resolve } from '#core';
+import { type Tree } from '#tree';
+
+// ── Mountable Tree ──
+
+type ResolveResult = { store: Tree; mountPath: string | null; parentStore: Tree };
+
+export function withMounts(rootStore: Tree): Tree {
+  const cache = new Map<string, Tree>();
+  const MAX_MOUNT_CACHE = 1000;
+
+  // Cached parametrized mount patterns — avoids depth-5 scan on every resolveStore miss
+  type ParamPattern = { regex: RegExp; paramNames: string[]; node: NodeData };
+  const paramPatterns = new Map<string, ParamPattern[]>();
+
+  const self: Tree = {
+    async get(path, ctx) {
+      const { store, mountPath, parentStore } = await resolveStore(path, ctx);
+      // Mount node config lives in parent store
+      if (mountPath === path) return parentStore.get(path, ctx);
+      return store.get(path, ctx);
+    },
+
+    async getChildren(path, opts, ctx) {
+      const { store } = await resolveStore(path, ctx);
+      return store.getChildren(path, opts, ctx);
+    },
+
+    async set(node, ctx) {
+      const { store, mountPath, parentStore } = await resolveStore(node.$path, ctx);
+      if (mountPath === node.$path) await parentStore.set(node, ctx);
+      else await store.set(node, ctx);
+      // Invalidate param pattern cache AFTER write (cache may have been populated with stale empty results during resolveStore)
+      if (node.$path.includes(':') && isComponent(node['mount'])) paramPatterns.clear();
+    },
+
+    async remove(path, ctx) {
+      const { store, mountPath, parentStore } = await resolveStore(path, ctx);
+      if (mountPath === path) {
+        // Stop caching this mount
+        cache.delete(path);
+        return parentStore.remove(path, ctx);
+      }
+      return store.remove(path, ctx);
+    },
+
+    async patch(path, ops, ctx) {
+      const { store, mountPath, parentStore } = await resolveStore(path, ctx);
+      if (mountPath === path) await parentStore.patch(path, ops, ctx);
+      else await store.patch(path, ops, ctx);
+    },
+  };
+
+  /** Check if node's mount component resolves to a known adapter */
+  function isMountPoint(node: NodeData): boolean {
+    const mount = node['mount'];
+    if (!isComponent(mount)) return false;
+    // Refs need resolution — treat as mount-point optimistically
+    if (isRef(mount)) return true;
+    return !!resolve(mount.$type, 'mount');
+  }
+
+  async function resolveMount(node: NodeData, currentStore: Tree, ctx?: any): Promise<Tree> {
+    const mount = node['mount'];
+    if (!isComponent(mount)) throw new Error(`Mount component missing on ${node.$path}`);
+    let configNode = node;
+    if (isRef(mount)) {
+      configNode = (await currentStore.get(mount.$ref, ctx)) as NodeData;
+      if (!configNode) throw new Error(`Mount ref not found: ${mount.$ref}`);
+    }
+    const adapterType = isRef(mount) ? configNode.$type : mount.$type;
+    const adapter = resolve(adapterType, 'mount');
+    if (!adapter) throw new Error(`No adapter for type "${adapterType}"`);
+    return await adapter(configNode, currentStore, ctx, self);
+  }
+
+  // Parse path string like /users/:userId into regex and parameter names
+  function parseParametrizedPath(template: string) {
+    const paramNames: string[] = [];
+    const regexStr = template.replace(/:([a-zA-Z0-9_]+)/g, (_, paramName) => {
+      paramNames.push(paramName);
+      return '([^/]+)';
+    });
+    return {
+      regex: new RegExp(`^${regexStr}$`),
+      paramNames,
+    };
+  }
+
+  // Bind parameters in a string template, e.g. { source: '/users/:userId/orders' } + { userId: 1 } -> '/users/1/orders'
+  // Also recursively handles nested objects, replacing strings inside arrays/objects
+  function bindParams(obj: any, params: Record<string, string>): any {
+    if (typeof obj === 'string') {
+      return obj.replace(/:([a-zA-Z0-9_]+)/g, (match, paramName) => {
+        const val = params[paramName];
+        if (val === undefined) return match;
+        // Prevent sift operator injection: reject $-prefixed values in path params
+        if (val.startsWith('$')) throw new Error(`Invalid parameter value: ${paramName}=${val}`);
+        return val;
+      });
+    }
+    if (Array.isArray(obj)) {
+      return obj.map(item => bindParams(item, params));
+    }
+    if (typeof obj === 'object' && obj !== null) {
+      const result: Record<string, any> = {};
+      for (const [key, value] of Object.entries(obj)) {
+        result[key] = bindParams(value, params);
+      }
+      return result;
+    }
+    return obj;
+  }
+
+  async function resolveStore(path: string, ctx?: any): Promise<ResolveResult> {
+    // Walk: /, /seg1, /seg1/seg2, ... — each may be a mount point
+    // Nested mounts: check each level in the current best store
+    const segments = path.split('/').filter(Boolean);
+    const checks = ['/'];
+    for (let i = 0; i < segments.length; i++) checks.push('/' + segments.slice(0, i + 1).join('/'));
+
+    let bestStore = rootStore;
+    let bestMountPath: string | null = null;
+    let parentStore = rootStore;
+
+    for (const check of checks) {
+      // We need to look for parameterized mounts in the current best store's config nodes if check isn't exactly matching.
+      // But first, let's keep the existing logic for direct matches
+      const cacheKey = ctx?.userId ? `${check}?uid=${ctx.userId}` : check;
+      const cached = cache.get(cacheKey);
+      if (cached) {
+        parentStore = bestStore;
+        bestStore = cached;
+        bestMountPath = check;
+        continue;
+      }
+
+      let node = await bestStore.get(check, ctx);
+      let matchParams: Record<string, string> | undefined = undefined;
+
+      // If no direct node, look for parameterized mounts (cached)
+      if (!node) {
+        const parts = check.split('/').filter(Boolean);
+        let parentCheck = '/';
+        for (let j = parts.length - 1; j >= 0; j--) {
+           const candidate = '/' + parts.slice(0, j).join('/');
+           const pNode = await bestStore.get(candidate || '/', ctx);
+           if (pNode) {
+              parentCheck = candidate || '/';
+              break;
+           }
+        }
+
+        // Scan once per prefix, cache compiled patterns
+        let patterns = paramPatterns.get(parentCheck);
+        if (!patterns) {
+          patterns = [];
+          const children = await bestStore.getChildren(parentCheck, { depth: 5 }, ctx);
+          for (const child of children.items) {
+            if (child.$path.includes(':') && isComponent(child['mount'])) {
+              patterns.push({ ...parseParametrizedPath(child.$path), node: child });
+            }
+          }
+          paramPatterns.set(parentCheck, patterns);
+        }
+
+        for (const p of patterns) {
+          const match = check.match(p.regex);
+          if (match) {
+            node = p.node;
+            matchParams = {};
+            for (let i = 0; i < p.paramNames.length; i++) {
+              matchParams[p.paramNames[i]] = match[i + 1];
+            }
+            break;
+          }
+        }
+      }
+
+      if (!node || !isMountPoint(node)) continue;
+
+      // If we matched parameters, bind them into the node config
+      let configNode = node;
+      if (matchParams) {
+          // deep copy and bind parameters for 'query' component or other configs
+          configNode = bindParams(node, matchParams);
+      }
+
+      const store = await resolveMount(configNode, bestStore, ctx);
+      // Evict oldest entry if cache is full
+      if (cache.size >= MAX_MOUNT_CACHE) {
+        const first = cache.keys().next().value;
+        if (first) cache.delete(first);
+      }
+      cache.set(cacheKey, store);
+      parentStore = bestStore;
+      bestStore = store;
+      bestMountPath = check;
+    }
+    return { store: bestStore, mountPath: bestMountPath, parentStore };
+  }
+
+  return self;
+}

package/src/server/prefab.test.ts

@@ -0,0 +1,415 @@
+import { createNode, type NodeData } from '#core';
+import { clearPrefabs, getModPrefabs, getPrefab, getRegisteredMods, getSeedPrefabs, registerPrefab } from '#mod/prefab';
+import { createMemoryTree, type Tree } from '#tree';
+import assert from 'node:assert/strict';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { createModsStore } from './mods-mount';
+import { deployByKey, deployPrefab, deploySeedPrefabs } from './prefab';
+
+describe('Prefab registry', () => {
+  beforeEach(() => clearPrefabs());
+  afterEach(() => clearPrefabs());
+
+  it('registerPrefab stores and getPrefab retrieves', () => {
+    registerPrefab('orders', 'infra', [
+      { $path: 'data', $type: 'mount-point' } as NodeData,
+    ]);
+    const entry = getPrefab('orders', 'infra');
+    assert.ok(entry);
+    assert.equal(entry.nodes.length, 1);
+    assert.equal(entry.nodes[0].$type, 'mount-point');
+  });
+
+  it('sealed: duplicate registerPrefab is no-op', () => {
+    registerPrefab('a', 'b', [{ $path: 'x', $type: 'dir' } as NodeData]);
+    registerPrefab('a', 'b', [{ $path: 'y', $type: 'other' } as NodeData]);
+    assert.equal(getPrefab('a', 'b')!.nodes[0].$path, 'x');
+  });
+
+  it('getModPrefabs returns all prefabs for a mod', () => {
+    registerPrefab('orders', 'infra', [{ $path: '.', $type: 'dir' } as NodeData]);
+    registerPrefab('orders', 'demo', [{ $path: 'x', $type: 'dir' } as NodeData]);
+    registerPrefab('sim', 'world', [{ $path: '.', $type: 'dir' } as NodeData]);
+
+    const ordersPrefabs = getModPrefabs('orders');
+    assert.equal(ordersPrefabs.length, 2);
+    assert.deepEqual(ordersPrefabs.map(([n]) => n).sort(), ['demo', 'infra']);
+  });
+
+  it('getRegisteredMods returns unique mod names', () => {
+    registerPrefab('orders', 'infra', [{ $path: '.', $type: 'dir' } as NodeData]);
+    registerPrefab('orders', 'demo', [{ $path: 'x', $type: 'dir' } as NodeData]);
+    registerPrefab('sim', 'world', [{ $path: '.', $type: 'dir' } as NodeData]);
+
+    const mods = getRegisteredMods();
+    assert.deepEqual(mods.sort(), ['orders', 'sim']);
+  });
+
+  it('getPrefab returns undefined for missing', () => {
+    assert.equal(getPrefab('nope', 'nope'), undefined);
+  });
+});
+
+describe('Mods mount', () => {
+  let backing: Tree;
+
+  beforeEach(() => {
+    clearPrefabs();
+    backing = createMemoryTree();
+  });
+  afterEach(() => clearPrefabs());
+
+  it('get /sys/mods returns dir', async () => {
+    const ms = createModsStore(backing);
+    const node = await ms.get('/sys/mods');
+    assert.equal(node?.$type, 't.dir');
+  });
+
+  it('get /sys/mods/{mod} returns t.mod for registered mod', async () => {
+    registerPrefab('orders', 'infra', [{ $path: 'data', $type: 'dir' } as NodeData]);
+    const ms = createModsStore(backing);
+    const node = await ms.get('/sys/mods/orders');
+    assert.equal(node?.$type, 't.mod');
+    assert.equal((node as any).name, 'orders');
+    assert.deepEqual((node as any).prefabs, ['infra']);
+  });
+
+  it('get returns undefined for unregistered mod', async () => {
+    const ms = createModsStore(backing);
+    const node = await ms.get('/sys/mods/nope');
+    assert.equal(node, undefined);
+  });
+
+  it('getChildren /sys/mods lists all mods', async () => {
+    registerPrefab('orders', 'infra', [{ $path: '.', $type: 'dir' } as NodeData]);
+    registerPrefab('sim', 'world', [{ $path: '.', $type: 'dir' } as NodeData]);
+    const ms = createModsStore(backing);
+    const { items } = await ms.getChildren('/sys/mods');
+    assert.equal(items.length, 2);
+    const paths = items.map(n => n.$path).sort();
+    assert.deepEqual(paths, ['/sys/mods/orders', '/sys/mods/sim']);
+  });
+
+  it('getChildren /sys/mods/{mod} lists prefabs dir', async () => {
+    registerPrefab('orders', 'infra', [{ $path: 'data', $type: 'dir' } as NodeData]);
+    const ms = createModsStore(backing);
+    const { items } = await ms.getChildren('/sys/mods/orders');
+    assert.ok(items.some(n => n.$path === '/sys/mods/orders/prefabs'));
+  });
+
+  it('getChildren /sys/mods/{mod}/prefabs lists prefab names', async () => {
+    registerPrefab('orders', 'infra', [{ $path: 'data', $type: 'dir' } as NodeData]);
+    registerPrefab('orders', 'demo', [{ $path: 'x', $type: 'dir' } as NodeData]);
+    const ms = createModsStore(backing);
+    const { items } = await ms.getChildren('/sys/mods/orders/prefabs');
+    assert.equal(items.length, 2);
+    const paths = items.map(n => n.$path).sort();
+    assert.deepEqual(paths, ['/sys/mods/orders/prefabs/demo', '/sys/mods/orders/prefabs/infra']);
+  });
+
+  it('getChildren lists prefab nodes (direct children only)', async () => {
+    registerPrefab('orders', 'infra', [
+      { $path: '.', $type: 'dir' } as NodeData,
+      { $path: 'data', $type: 'mount-point' } as NodeData,
+      { $path: 'kitchen', $type: 'mount-point' } as NodeData,
+      { $path: 'nested/deep', $type: 'dir' } as NodeData, // skipped — not direct
+      { $path: '/sys/autostart/x', $type: 'ref' } as NodeData, // skipped — absolute
+    ]);
+    const ms = createModsStore(backing);
+    const { items } = await ms.getChildren('/sys/mods/orders/prefabs/infra');
+    assert.equal(items.length, 2); // data + kitchen
+    assert.deepEqual(items.map(n => n.$path).sort(), [
+      '/sys/mods/orders/prefabs/infra/data',
+      '/sys/mods/orders/prefabs/infra/kitchen',
+    ]);
+  });
+
+  it('set throws (read-only)', async () => {
+    const ms = createModsStore(backing);
+    await assert.rejects(
+      () => ms.set(createNode('/sys/mods/x', 'dir')),
+      (e: Error) => e.message.includes('read-only'),
+    );
+  });
+
+  it('remove throws (read-only)', async () => {
+    const ms = createModsStore(backing);
+    await assert.rejects(
+      () => ms.remove('/sys/mods/x'),
+      (e: Error) => e.message.includes('read-only'),
+    );
+  });
+});
+
+describe('deployPrefab', () => {
+  let store: Tree;
+
+  beforeEach(() => {
+    clearPrefabs();
+    store = createMemoryTree();
+  });
+  afterEach(() => clearPrefabs());
+
+  it('deploys prefab nodes to target path', async () => {
+    registerPrefab('test', 'basic', [
+      { $path: '.', $type: 'dir' } as NodeData,
+      { $path: 'child', $type: 'item', label: 'Hello' } as NodeData,
+    ]);
+
+    const result = await deployPrefab(store, '/sys/mods/test/prefabs/basic', '/app', {});
+    assert.equal(result.deployed, 2);
+    assert.equal(result.skipped, 0);
+
+    const root = await store.get('/app');
+    assert.equal(root?.$type, 'dir');
+
+    const child = await store.get('/app/child');
+    assert.equal(child?.$type, 'item');
+    assert.equal((child as any).label, 'Hello');
+  });
+
+  it('idempotent: second deploy skips existing nodes', async () => {
+    registerPrefab('test', 'idem', [
+      { $path: 'a', $type: 'dir' } as NodeData,
+      { $path: 'b', $type: 'dir' } as NodeData,
+    ]);
+
+    await deployPrefab(store, '/sys/mods/test/prefabs/idem', '/x', {});
+    const result = await deployPrefab(store, '/sys/mods/test/prefabs/idem', '/x', {});
+    assert.equal(result.deployed, 0);
+    assert.equal(result.skipped, 2);
+  });
+
+  it('rejects absolute paths without allowAbsolute', async () => {
+    registerPrefab('test', 'abs', [
+      { $path: '/sys/autostart/svc', $type: 'ref', $ref: '/x' } as NodeData,
+    ]);
+
+    await assert.rejects(
+      () => deployPrefab(store, '/sys/mods/test/prefabs/abs', '/app', {}),
+      (e: Error) => e.message.includes('not allowed'),
+    );
+  });
+
+  it('allows absolute paths with allowAbsolute', async () => {
+    registerPrefab('test', 'abs2', [
+      { $path: 'local', $type: 'dir' } as NodeData,
+      { $path: '/sys/autostart/svc', $type: 'ref', $ref: '/app/svc' } as NodeData,
+    ]);
+
+    const result = await deployPrefab(store, '/sys/mods/test/prefabs/abs2', '/app', {
+      allowAbsolute: true,
+    });
+    assert.equal(result.deployed, 2);
+
+    const ref = await store.get('/sys/autostart/svc');
+    assert.equal(ref?.$type, 'ref');
+
+    const local = await store.get('/app/local');
+    assert.equal(local?.$type, 'dir');
+  });
+
+  it('setup transforms nodes before deploy', async () => {
+    registerPrefab('test', 'setup', [
+      { $path: 'cfg', $type: 'config', value: 'PLACEHOLDER' } as NodeData,
+    ], (nodes, params) => {
+      return nodes.map(n => n.$path === 'cfg'
+        ? { ...n, value: (params as any)?.value ?? 'default' }
+        : n
+      );
+    });
+
+    await deployPrefab(store, '/sys/mods/test/prefabs/setup', '/app', {
+      params: { value: 'custom' },
+    });
+
+    const cfg = await store.get('/app/cfg');
+    assert.equal((cfg as any).value, 'custom');
+  });
+
+  it('throws on invalid source path', async () => {
+    await assert.rejects(
+      () => deployPrefab(store, '/bad/path', '/app'),
+      (e: Error) => e.message.includes('Invalid prefab path'),
+    );
+  });
+
+  it('throws on missing prefab', async () => {
+    await assert.rejects(
+      () => deployPrefab(store, '/sys/mods/nope/prefabs/nope', '/app'),
+      (e: Error) => e.message.includes('not found'),
+    );
+  });
+
+  it('drops $rev from prefab nodes', async () => {
+    registerPrefab('test', 'rev', [
+      { $path: 'x', $type: 'dir', $rev: 42 } as NodeData,
+    ]);
+
+    await deployPrefab(store, '/sys/mods/test/prefabs/rev', '/app', {});
+    const node = await store.get('/app/x');
+    // $rev should be set by store (1), not prefab's 42
+    assert.notEqual(node?.$rev, 42);
+  });
+
+  it('async setup transforms nodes', async () => {
+    registerPrefab('test', 'async-setup', [
+      { $path: 'cfg', $type: 'config', value: '' } as NodeData,
+    ], async (nodes) => {
+      await new Promise(r => setTimeout(r, 1));
+      return nodes.map(n => ({ ...n, value: 'async-result' }));
+    });
+
+    await deployPrefab(store, '/sys/mods/test/prefabs/async-setup', '/app', {});
+    const cfg = await store.get('/app/cfg');
+    assert.equal((cfg as any).value, 'async-result');
+  });
+});
+
+describe('deployByKey', () => {
+  let store: Tree;
+
+  beforeEach(() => {
+    clearPrefabs();
+    store = createMemoryTree();
+  });
+  afterEach(() => clearPrefabs());
+
+  it('deploys prefab by mod+name without path parsing', async () => {
+    registerPrefab('mymod', 'stuff', [
+      { $path: '.', $type: 'dir' } as NodeData,
+      { $path: 'child', $type: 'item' } as NodeData,
+    ]);
+
+    const result = await deployByKey(store, 'mymod', 'stuff', '/target');
+    assert.equal(result.deployed, 2);
+
+    assert.equal((await store.get('/target'))?.$type, 'dir');
+    assert.equal((await store.get('/target/child'))?.$type, 'item');
+  });
+
+  it('throws on missing prefab', async () => {
+    await assert.rejects(
+      () => deployByKey(store, 'nope', 'nope', '/x'),
+      (e: Error) => e.message.includes('not found'),
+    );
+  });
+});
+
+describe('getSeedPrefabs', () => {
+  beforeEach(() => clearPrefabs());
+  afterEach(() => clearPrefabs());
+
+  it('returns only seed-named prefabs', () => {
+    registerPrefab('orders', 'seed', [{ $path: '.', $type: 'dir' } as NodeData]);
+    registerPrefab('orders', 'infra', [{ $path: '.', $type: 'dir' } as NodeData]);
+    registerPrefab('sim', 'seed', [{ $path: '.', $type: 'dir' } as NodeData]);
+
+    const seeds = getSeedPrefabs();
+    assert.equal(seeds.length, 2);
+    assert.deepEqual(seeds.map(([mod]) => mod).sort(), ['orders', 'sim']);
+  });
+
+  it('returns empty when no seed prefabs', () => {
+    registerPrefab('orders', 'infra', [{ $path: '.', $type: 'dir' } as NodeData]);
+    assert.equal(getSeedPrefabs().length, 0);
+  });
+});
+
+describe('deploySeedPrefabs', () => {
+  let store: Tree;
+
+  beforeEach(() => {
+    clearPrefabs();
+    store = createMemoryTree();
+  });
+  afterEach(() => {
+    clearPrefabs();
+    delete process.env.TENANT;
+  });
+
+  it('deploys all seed prefabs to root', async () => {
+    registerPrefab('alpha', 'seed', [
+      { $path: 'alpha', $type: 'dir' } as NodeData,
+      { $path: 'alpha/child', $type: 'item' } as NodeData,
+    ]);
+    registerPrefab('beta', 'seed', [
+      { $path: 'beta', $type: 'dir' } as NodeData,
+    ]);
+
+    await deploySeedPrefabs(store);
+
+    assert.equal((await store.get('/alpha'))?.$type, 'dir');
+    assert.equal((await store.get('/alpha/child'))?.$type, 'item');
+    assert.equal((await store.get('/beta'))?.$type, 'dir');
+  });
+
+  it('allows absolute paths in seed prefabs', async () => {
+    registerPrefab('svc', 'seed', [
+      { $path: 'svc', $type: 'service' } as NodeData,
+      { $path: '/sys/autostart/svc', $type: 'ref', $ref: '/svc' } as NodeData,
+    ]);
+
+    await deploySeedPrefabs(store);
+
+    assert.equal((await store.get('/svc'))?.$type, 'service');
+    assert.equal((await store.get('/sys/autostart/svc'))?.$type, 'ref');
+  });
+
+  it('TENANT mode skips non-core seeds', async () => {
+    process.env.TENANT = '1';
+
+    registerPrefab('core', 'seed', [
+      { $path: 'sys', $type: 'dir' } as NodeData,
+    ], undefined, { tier: 'core' });
+
+    registerPrefab('heavy', 'seed', [
+      { $path: 'heavy', $type: 'dir' } as NodeData,
+    ]);
+
+    await deploySeedPrefabs(store);
+
+    assert.equal((await store.get('/sys'))?.$type, 'dir');
+    assert.equal(await store.get('/heavy'), undefined);
+  });
+
+  it('non-TENANT mode deploys all seeds', async () => {
+    registerPrefab('core', 'seed', [
+      { $path: 'sys', $type: 'dir' } as NodeData,
+    ], undefined, { tier: 'core' });
+
+    registerPrefab('heavy', 'seed', [
+      { $path: 'heavy', $type: 'dir' } as NodeData,
+    ]);
+
+    await deploySeedPrefabs(store);
+
+    assert.equal((await store.get('/sys'))?.$type, 'dir');
+    assert.equal((await store.get('/heavy'))?.$type, 'dir');
+  });
+
+  it('seed prefab setup receives store in params', async () => {
+    let receivedStore: unknown = null;
+
+    registerPrefab('test', 'seed', [
+      { $path: 'test', $type: 'dir' } as NodeData,
+    ], (nodes, params) => {
+      receivedStore = (params as any)?.store;
+      return nodes;
+    });
+
+    await deploySeedPrefabs(store);
+
+    assert.equal(receivedStore, store);
+  });
+
+  it('idempotent on second run', async () => {
+    registerPrefab('idem', 'seed', [
+      { $path: 'idem', $type: 'dir' } as NodeData,
+    ]);
+
+    await deploySeedPrefabs(store);
+    await deploySeedPrefabs(store); // should not throw
+    assert.equal((await store.get('/idem'))?.$type, 'dir');
+  });
+});