@rangka/core 0.0.1

package/src/widgets/slot-validator.ts

@@ -0,0 +1,87 @@
+import type { WidgetNode } from '@rangka/shared';
+import type { WidgetRegistry } from './widget-registry.js';
+
+export interface SlotValidationError {
+  path: string;
+  message: string;
+}
+
+export function validatePageBody(
+  body: WidgetNode[],
+  widgetRegistry: WidgetRegistry,
+): SlotValidationError[] {
+  return validateWidgetNodes(body, widgetRegistry, 'body');
+}
+
+function validateWidgetNodes(
+  nodes: WidgetNode[],
+  registry: WidgetRegistry,
+  basePath: string,
+): SlotValidationError[] {
+  const errors: SlotValidationError[] = [];
+
+  nodes.forEach((node, index) => {
+    const path = `${basePath}[${index}]`;
+    const def = registry.get(node.type);
+
+    if (!def) {
+      errors.push({ path, message: `Unknown widget type: '${node.type}'` });
+      return;
+    }
+
+    if (node.children && node.children.length > 0) {
+      if (!def.container) {
+        errors.push({ path, message: `Widget '${node.type}' is not a container but has children` });
+      } else if (def.accepts) {
+        for (let i = 0; i < node.children.length; i++) {
+          const child = node.children[i];
+          if (!def.accepts.includes(child.type)) {
+            errors.push({
+              path: `${path}.children[${i}]`,
+              message: `Widget '${node.type}' does not accept child type '${child.type}'`,
+            });
+          }
+        }
+      }
+    }
+
+    if (node.on) {
+      for (const trigger of Object.keys(node.on)) {
+        if (!def.triggers.includes(trigger)) {
+          errors.push({
+            path: `${path}.on.${trigger}`,
+            message: `Unknown trigger '${trigger}' on widget '${node.type}'`,
+          });
+        }
+      }
+    }
+
+    if (node.bind) {
+      const bindMode = getBindMode(node.bind);
+      if (def.binding === 'none' && bindMode !== 'none') {
+        errors.push({
+          path: `${path}.bind`,
+          message: `Widget '${node.type}' does not support data binding`,
+        });
+      } else if (def.binding === 'model' && bindMode !== 'model' && bindMode !== 'expression') {
+        errors.push({
+          path: `${path}.bind`,
+          message: `Widget '${node.type}' expects binding mode '${def.binding}' but got '${bindMode}'`,
+        });
+      }
+    }
+
+    if (node.children) {
+      errors.push(...validateWidgetNodes(node.children, registry, `${path}.children`));
+    }
+  });
+
+  return errors;
+}
+
+function getBindMode(bind: { field?: string; expression?: string; model?: unknown }): string {
+  if (bind.field) return 'field';
+  if (bind.expression) return 'expression';
+  if (bind.model) return 'model';
+  return 'none';
+}

package/src/widgets/widget-registry.ts

@@ -0,0 +1,32 @@
+import type { WidgetDefinitionMeta } from '@rangka/shared';
+
+export class WidgetRegistry {
+  private widgets = new Map<string, WidgetDefinitionMeta>();
+
+  register(definition: WidgetDefinitionMeta): void {
+    if (this.widgets.has(definition.name)) {
+      throw new Error(`Widget '${definition.name}' is already registered`);
+    }
+    this.widgets.set(definition.name, definition);
+  }
+
+  get(name: string): WidgetDefinitionMeta | undefined {
+    return this.widgets.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.widgets.has(name);
+  }
+
+  getAll(): WidgetDefinitionMeta[] {
+    return [...this.widgets.values()];
+  }
+
+  names(): string[] {
+    return [...this.widgets.keys()];
+  }
+
+  clear(): void {
+    this.widgets.clear();
+  }
+}

package/tests/boot.test.ts

@@ -0,0 +1,323 @@
+import { describe, it, expect, vi } from 'vitest';
+import { boot } from '../src/boot/index.js';
+import { MemoryDiscoverySource } from '../src/boot/discovery.js';
+import type { DiscoveredApp, RangkaPackageInfo } from '../src/boot/types.js';
+import { field } from '@rangka/shared';
+
+vi.mock('../src/db/client.js', () => {
+  const mockUser = {
+    id: 'u1',
+    email: 'admin@test.com',
+    full_name: 'Admin',
+    enabled: true,
+    password_hash: 'hashed',
+  };
+  const mockSession = {
+    id: 's1',
+    token: 'test-token',
+    user_id: 'u1',
+    expires_at: new Date(Date.now() + 60000).toISOString(),
+  };
+  const mockRole = { id: 'r1', name: 'Administrator' };
+  const mockUserRole = { user_id: 'u1', role_id: 'r1' };
+
+  return {
+    DatabaseClient: class MockDatabaseClient {
+      kysely = { fn: { countAll: () => ({ as: () => 'count' }) } };
+      async verifyConnection() {}
+      selectFrom(table: string) {
+        const q: any = {};
+        q.select = () => q;
+        q.selectAll = () => q;
+        q.where = (field: string, _op: string, value: any) => {
+          q._filter = { field, value };
+          return q;
+        };
+        q.orderBy = () => q;
+        q.offset = () => q;
+        q.limit = () => q;
+        q.values = () => q;
+        q.set = () => q;
+        q.returningAll = () => q;
+        q.execute = async () => {
+          if (table === 'core.user_role' && q._filter?.value === 'u1') return [mockUserRole];
+          if (table === 'core.role') return [mockRole];
+          return [];
+        };
+        q.executeTakeFirst = async () => {
+          if (table === 'core.session' && q._filter?.value === 'test-token') return mockSession;
+          if (table === 'core.user' && q._filter?.value === 'u1') return mockUser;
+          return { count: '0' };
+        };
+        q.executeTakeFirstOrThrow = async () => ({});
+        return q;
+      }
+      insertInto() {
+        return this.selectFrom('');
+      }
+      updateTable() {
+        return this.selectFrom('');
+      }
+      deleteFrom() {
+        return this.selectFrom('');
+      }
+    },
+  };
+});
+
+vi.mock('../src/db/auto-sync.js', () => ({
+  autoSync: vi.fn(async () => {}),
+}));
+
+function makeDiscoveredApp(
+  name: string,
+  deps: string[],
+  schemas: DiscoveredApp['schemas'] = [],
+  extensions: DiscoveredApp['extensions'] = [],
+): DiscoveredApp {
+  return {
+    packageInfo: {
+      packageName: `@rangka/${name}`,
+      path: `/fake/${name}`,
+      rangka: { type: 'app', entrypoint: './module.ts' },
+    },
+    config: { name, label: name, depends: deps },
+    schemas,
+    extensions,
+  };
+}
+
+describe('boot', () => {
+  it('orchestrates full pipeline: discovery → sort → load → merge → registry', async () => {
+    const packages: RangkaPackageInfo[] = [
+      {
+        packageName: '@rangka/core',
+        path: '/fake/core',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+      {
+        packageName: '@rangka/sales',
+        path: '/fake/sales',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+      {
+        packageName: '@rangka/project',
+        path: '/fake/project',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+    ];
+
+    const apps: DiscoveredApp[] = [
+      makeDiscoveredApp(
+        'core',
+        [],
+        [
+          {
+            module: 'auth',
+            schema: { name: 'user', fields: { email: field.string({ required: true }) } },
+          },
+        ],
+      ),
+      makeDiscoveredApp(
+        'sales',
+        ['core'],
+        [
+          {
+            module: 'sales',
+            schema: {
+              name: 'customer',
+              label: 'Customer',
+              fields: { name: field.string({ required: true }), email: field.string() },
+              traits: ['timestamped'],
+            },
+          },
+          {
+            module: 'sales',
+            schema: {
+              name: 'invoice',
+              label: 'Sales Invoice',
+              fields: {
+                customer: field.link('customer'),
+                total: field.decimal(),
+              },
+              traits: ['timestamped'],
+            },
+          },
+        ],
+      ),
+      makeDiscoveredApp(
+        'project',
+        ['sales'],
+        [
+          {
+            module: 'custom',
+            schema: { name: 'task', fields: { title: field.string() } },
+          },
+        ],
+        [
+          {
+            target: 'sales.customer',
+            config: { fields: { loyalty_points: field.int({ default: 0 }) } },
+          },
+        ],
+      ),
+    ];
+
+    const { registry } = await boot({
+      discoverySource: new MemoryDiscoverySource(packages),
+      apps,
+    });
+
+    expect(registry.getAllModels().length).toBeGreaterThanOrEqual(4);
+
+    const customer = registry.getModel('sales.customer');
+    expect(customer).toBeDefined();
+    expect(customer!.label).toBe('Customer');
+
+    const customerFields = registry.getFieldsForModel('sales.customer');
+    const fieldNames = customerFields.map((f) => f.name);
+    expect(fieldNames).toContain('name');
+    expect(fieldNames).toContain('email');
+    expect(fieldNames).toContain('created_at');
+    expect(fieldNames).toContain('loyalty_points');
+
+    const loyaltyField = customerFields.find((f) => f.name === 'loyalty_points')!;
+    expect(loyaltyField.provenance).toEqual({ source: 'extension', app: 'project' });
+
+    const invoice = registry.getModel('sales.invoice');
+    expect(invoice).toBeDefined();
+    const invoiceFieldNames = invoice!.fields.map((f) => f.name);
+    expect(invoiceFieldNames).toContain('created_at');
+    expect(invoiceFieldNames).toContain('customer');
+
+    const rels = registry.getRelationshipsForModel('sales.invoice');
+    const customerRel = rels.find((r) => r.field === 'customer');
+    expect(customerRel).toBeDefined();
+    expect(customerRel!.type).toBe('link');
+    expect(customerRel!.to).toBe('sales.customer');
+
+    const extSources = registry.getExtensionSources('sales.customer');
+    expect(extSources).toHaveLength(1);
+    expect(extSources[0].app).toBe('project');
+    expect(extSources[0].fields).toContain('loyalty_points');
+  });
+
+  it('resolves traits before extensions can reference them', async () => {
+    const apps: DiscoveredApp[] = [
+      makeDiscoveredApp('core', [], []),
+      makeDiscoveredApp(
+        'sales',
+        ['core'],
+        [
+          {
+            module: 'sales',
+            schema: {
+              name: 'order',
+              fields: { total: field.decimal() },
+              traits: ['timestamped'],
+            },
+          },
+        ],
+      ),
+    ];
+
+    const { registry } = await boot({
+      discoverySource: new MemoryDiscoverySource([]),
+      apps,
+    });
+
+    const order = registry.getModel('sales.order')!;
+    const createdAtField = order.fields.find((f) => f.name === 'created_at');
+    expect(createdAtField).toBeDefined();
+    expect(createdAtField!.provenance.source).toBe('trait');
+  });
+
+  it('boot with server config generates accessible routes', async () => {
+    const apps: DiscoveredApp[] = [
+      makeDiscoveredApp(
+        'core',
+        [],
+        [
+          {
+            module: 'crm',
+            schema: {
+              name: 'contact',
+              fields: { name: field.string({ required: true }), email: field.string() },
+            },
+          },
+        ],
+      ),
+    ];
+
+    const { registry, server } = await boot({
+      discoverySource: new MemoryDiscoverySource([]),
+      apps,
+      database: { host: 'localhost', database: 'test', user: 'test', password: 'test' },
+      server: { port: 3000 },
+    });
+
+    expect(server).toBeDefined();
+    expect(registry.getModel('crm.contact')).toBeDefined();
+
+    const listRes = await server!.inject({
+      method: 'GET',
+      url: '/api/crm/contact',
+      headers: { authorization: 'Bearer test-token' },
+    });
+    expect(listRes.statusCode).toBe(200);
+
+    const getRes = await server!.inject({
+      method: 'GET',
+      url: '/api/crm/contact/1',
+      headers: { authorization: 'Bearer test-token' },
+    });
+    expect([200, 404]).toContain(getRes.statusCode);
+
+    const postRes = await server!.inject({
+      method: 'POST',
+      url: '/api/crm/contact',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer test-token' },
+      payload: JSON.stringify({ name: 'Test' }),
+    });
+    expect([201, 400, 500]).toContain(postRes.statusCode);
+  });
+
+  it('boot registers custom apiDefinitions on the server', async () => {
+    const apps: DiscoveredApp[] = [
+      {
+        ...makeDiscoveredApp(
+          'core',
+          [],
+          [
+            {
+              module: 'crm',
+              schema: { name: 'lead', fields: { name: field.string() } },
+            },
+          ],
+        ),
+        apiDefinitions: [
+          {
+            method: 'GET' as const,
+            path: '/api/custom/stats',
+            handler: async (_request: any, reply: any) => {
+              return reply.send({ count: 42 });
+            },
+          },
+        ],
+      },
+    ];
+
+    const { server } = await boot({
+      discoverySource: new MemoryDiscoverySource([]),
+      apps,
+      database: { host: 'localhost', database: 'test', user: 'test', password: 'test' },
+      server: { port: 3001 },
+    });
+
+    expect(server).toBeDefined();
+    const res = await server!.inject({ method: 'GET', url: '/api/custom/stats' });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.count).toBe(42);
+  });
+});

package/tests/dependency-sort.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import { dependencySort } from '../src/boot/dependency-sort.js';
+import { CircularDependencyError, MissingDependencyError } from '../src/boot/types.js';
+import type { AppConfig } from '@rangka/shared';
+
+describe('dependencySort', () => {
+  it('sorts a linear chain correctly', () => {
+    const apps: AppConfig[] = [
+      { name: 'project', depends: ['sales'] },
+      { name: 'core' },
+      { name: 'sales', depends: ['core'] },
+    ];
+
+    const sorted = dependencySort(apps);
+    const names = sorted.map((a) => a.name);
+
+    expect(names).toEqual(['core', 'sales', 'project']);
+  });
+
+  it('handles diamond dependencies', () => {
+    const apps: AppConfig[] = [
+      { name: 'core' },
+      { name: 'sales', depends: ['core'] },
+      { name: 'accounting', depends: ['core'] },
+      { name: 'project', depends: ['sales', 'accounting'] },
+    ];
+
+    const sorted = dependencySort(apps);
+    const names = sorted.map((a) => a.name);
+
+    expect(names[0]).toBe('core');
+    expect(names[names.length - 1]).toBe('project');
+    expect(names.indexOf('accounting')).toBeLessThan(names.indexOf('project'));
+    expect(names.indexOf('sales')).toBeLessThan(names.indexOf('project'));
+  });
+
+  it('uses alphabetical tiebreaker for same-level apps', () => {
+    const apps: AppConfig[] = [
+      { name: 'core' },
+      { name: 'zebra', depends: ['core'] },
+      { name: 'alpha', depends: ['core'] },
+      { name: 'middle', depends: ['core'] },
+    ];
+
+    const sorted = dependencySort(apps);
+    const names = sorted.map((a) => a.name);
+
+    expect(names).toEqual(['core', 'alpha', 'middle', 'zebra']);
+  });
+
+  it('always places core first', () => {
+    const apps: AppConfig[] = [{ name: 'sales', depends: [] }, { name: 'core' }];
+
+    const sorted = dependencySort(apps);
+    expect(sorted[0].name).toBe('core');
+  });
+
+  it('throws CircularDependencyError for direct cycle', () => {
+    const apps: AppConfig[] = [
+      { name: 'core' },
+      { name: 'a', depends: ['b'] },
+      { name: 'b', depends: ['a'] },
+    ];
+
+    expect(() => dependencySort(apps)).toThrow(CircularDependencyError);
+  });
+
+  it('throws CircularDependencyError for indirect cycle', () => {
+    const apps: AppConfig[] = [
+      { name: 'core' },
+      { name: 'a', depends: ['b'] },
+      { name: 'b', depends: ['c'] },
+      { name: 'c', depends: ['a'] },
+    ];
+
+    expect(() => dependencySort(apps)).toThrow(CircularDependencyError);
+    try {
+      dependencySort(apps);
+    } catch (e) {
+      const err = e as CircularDependencyError;
+      expect(err.cycle).toContain('a');
+      expect(err.cycle).toContain('b');
+      expect(err.cycle).toContain('c');
+    }
+  });
+
+  it('throws MissingDependencyError for unknown dependency', () => {
+    const apps: AppConfig[] = [{ name: 'core' }, { name: 'project', depends: ['sales'] }];
+
+    expect(() => dependencySort(apps)).toThrow(MissingDependencyError);
+    try {
+      dependencySort(apps);
+    } catch (e) {
+      const err = e as MissingDependencyError;
+      expect(err.app).toBe('project');
+      expect(err.missingDep).toBe('sales');
+    }
+  });
+});

package/tests/discovery.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest';
+import { NodeModulesDiscoverySource, MemoryDiscoverySource } from '../src/boot/discovery.js';
+import type { RangkaPackageInfo } from '../src/boot/types.js';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+describe('MemoryDiscoverySource', () => {
+  it('returns configured packages', async () => {
+    const packages: RangkaPackageInfo[] = [
+      {
+        packageName: '@rangka/sales',
+        path: '/fake/node_modules/@rangka/sales',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+      {
+        packageName: 'rangka-custom',
+        path: '/fake/node_modules/rangka-custom',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+    ];
+
+    const source = new MemoryDiscoverySource(packages);
+    const result = await source.findRangkaPackages();
+
+    expect(result).toEqual(packages);
+    expect(result).toHaveLength(2);
+  });
+
+  it('returns empty array when no packages configured', async () => {
+    const source = new MemoryDiscoverySource([]);
+    const result = await source.findRangkaPackages();
+    expect(result).toEqual([]);
+  });
+});
+
+describe('NodeModulesDiscoverySource', () => {
+  let tmpDir: string;
+
+  async function setupFakeNodeModules(packages: Record<string, object>) {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'rangka-test-'));
+    const nodeModules = path.join(tmpDir, 'node_modules');
+    await fs.mkdir(nodeModules, { recursive: true });
+
+    for (const [name, pkgJson] of Object.entries(packages)) {
+      const pkgDir = path.join(nodeModules, name);
+      await fs.mkdir(pkgDir, { recursive: true });
+      await fs.writeFile(path.join(pkgDir, 'package.json'), JSON.stringify(pkgJson));
+    }
+
+    return tmpDir;
+  }
+
+  it('discovers packages with rangka field', async () => {
+    const root = await setupFakeNodeModules({
+      'my-app': {
+        name: 'my-app',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+    });
+
+    const source = new NodeModulesDiscoverySource(root);
+    const result = await source.findRangkaPackages();
+
+    expect(result).toHaveLength(1);
+    expect(result[0].packageName).toBe('my-app');
+    expect(result[0].rangka.type).toBe('app');
+    expect(result[0].rangka.entrypoint).toBe('./app.ts');
+  });
+
+  it('ignores packages without rangka field', async () => {
+    const root = await setupFakeNodeModules({
+      lodash: { name: 'lodash', version: '4.0.0' },
+      'my-app': {
+        name: 'my-app',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+    });
+
+    const source = new NodeModulesDiscoverySource(root);
+    const result = await source.findRangkaPackages();
+
+    expect(result).toHaveLength(1);
+    expect(result[0].packageName).toBe('my-app');
+  });
+
+  it('discovers scoped packages', async () => {
+    const root = await setupFakeNodeModules({
+      '@rangka/sales': {
+        name: '@rangka/sales',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+      '@rangka/accounting': {
+        name: '@rangka/accounting',
+        rangka: { type: 'app', entrypoint: './dist/app.js' },
+      },
+    });
+
+    const source = new NodeModulesDiscoverySource(root);
+    const result = await source.findRangkaPackages();
+
+    expect(result).toHaveLength(2);
+    const names = result.map((r) => r.packageName).sort();
+    expect(names).toEqual(['@rangka/accounting', '@rangka/sales']);
+  });
+
+  it('discovers both scoped and unscoped packages', async () => {
+    const root = await setupFakeNodeModules({
+      '@rangka/sales': {
+        name: '@rangka/sales',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+      'rangka-custom-app': {
+        name: 'rangka-custom-app',
+        rangka: { type: 'app', entrypoint: './app.ts' },
+      },
+    });
+
+    const source = new NodeModulesDiscoverySource(root);
+    const result = await source.findRangkaPackages();
+
+    expect(result).toHaveLength(2);
+    const names = result.map((r) => r.packageName).sort();
+    expect(names).toEqual(['@rangka/sales', 'rangka-custom-app']);
+  });
+});