@rangka/core 0.0.1

package/src/hooks/context.ts

@@ -0,0 +1,89 @@
+import type { Kysely } from 'kysely';
+import type { FrameworkContext } from '@rangka/shared';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { RequestContext } from '../auth/types.js';
+import type { EventBus } from '../events/bus.js';
+import type { ServiceRegistry } from '../services/registry.js';
+import type { AdapterRegistry } from '../plugins/adapter-registry.js';
+import { enqueue } from '../jobs/enqueue.js';
+import { createModelAccess } from '../model-api/index.js';
+
+export interface HookContextOptions {
+  trx: unknown;
+  schema: SchemaRegistry;
+  auth: RequestContext;
+  eventBus?: EventBus;
+  serviceRegistry?: ServiceRegistry;
+  config?: Record<string, unknown>;
+  adapterRegistry?: AdapterRegistry;
+}
+
+/**
+ * Build a full FrameworkContext for hooks, scoped to the current transaction and auth.
+ */
+export function createHookContext(opts: HookContextOptions): FrameworkContext {
+  const { trx, schema, auth, eventBus, serviceRegistry, config = {}, adapterRegistry } = opts;
+
+  const transaction = trx as Kysely<unknown>;
+
+  const events = {
+    emit: async (event: string, payload: unknown) => {
+      if (eventBus) {
+        await eventBus.emitWithTrx(event, payload, transaction);
+      }
+    },
+    on: (event: string, handler: (payload: unknown) => Promise<void>) => {
+      eventBus?.on(event, handler);
+    },
+  };
+
+  const enqueueJob = async (
+    job: string,
+    data: unknown,
+    opts?: { delay?: number; unique?: boolean; uniqueKey?: string },
+  ) => {
+    await enqueue(transaction, job, data, opts);
+  };
+
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  const models = createModelAccess({
+    db: transaction as any,
+    registry: schema,
+    auth,
+    adapterRegistry,
+  });
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+
+  const service = (name: string) => {
+    if (!serviceRegistry) {
+      throw new Error('ServiceRegistry not available in this context');
+    }
+    return serviceRegistry.get(name, {
+      db: transaction,
+      schema,
+      enqueue: enqueueJob,
+      events,
+      config,
+      models,
+      auth: { user: auth.user ?? null, roles: auth.roles ?? [] },
+      scope: auth.scopeFilters?.[0]?.value ?? null,
+    });
+  };
+
+  return {
+    db: transaction,
+    schema,
+    auth: {
+      user: auth.user ?? null,
+      roles: auth.roles ?? [],
+    },
+    scope: auth.scopeFilters?.[0]?.value ?? null,
+    models,
+    events,
+    config,
+    service,
+    enqueue: enqueueJob,
+    notify: () => {},
+    email: { send: async () => {} },
+  };
+}

package/src/hooks/errors.ts

@@ -0,0 +1,11 @@
+export class ValidationError extends Error {
+  public readonly field?: string;
+  public readonly code: string;
+
+  constructor(field: string, message: string) {
+    super(message);
+    this.name = 'ValidationError';
+    this.field = field;
+    this.code = 'VALIDATION_ERROR';
+  }
+}

package/src/hooks/executor.ts

@@ -0,0 +1,115 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Kysely } from 'kysely';
+import type { HooksConfig } from '@rangka/shared';
+import type { HookChain, HookContext, HookDocument } from './types.js';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { RequestContext } from '../auth/types.js';
+import type { EventBus } from '../events/bus.js';
+import type { ServiceRegistry } from '../services/registry.js';
+import { createHookContext } from './context.js';
+
+export type HookOperation = 'create' | 'update' | 'delete' | 'submit' | 'cancel';
+
+export interface ExecutePipelineOptions {
+  model: string;
+  operation: HookOperation;
+  chain: HookChain;
+  doc: HookDocument;
+  db: Kysely<any>;
+  schema: SchemaRegistry;
+  auth: RequestContext;
+  eventBus?: EventBus;
+  serviceRegistry?: ServiceRegistry;
+  config?: Record<string, unknown>;
+  execute: (doc: HookDocument, trx: Kysely<any>) => Promise<HookDocument>;
+}
+
+/**
+ * Run the full hook pipeline for a mutation operation.
+ * Transaction covers: validate -> beforeSave -> before{Op} -> execute -> after{Op}
+ * afterSave runs AFTER the transaction commits (cannot roll back the write).
+ */
+export async function executeHookPipeline(opts: ExecutePipelineOptions): Promise<HookDocument> {
+  const { chain, operation, db, schema, auth, eventBus, serviceRegistry, config, execute } = opts;
+  const doc = { ...opts.doc };
+
+  const beforeHookKey = `before${capitalize(operation)}` as keyof HooksConfig;
+  const afterHookKey = `after${capitalize(operation)}` as keyof HooksConfig;
+
+  const result = await db.transaction().execute(async (trx) => {
+    const ctx: HookContext = createHookContext({
+      trx,
+      schema,
+      auth,
+      eventBus,
+      serviceRegistry,
+      config,
+    });
+
+    // Step 1: Run synchronous validators (skip for delete)
+    if (operation !== 'delete') {
+      runValidators(chain, doc);
+    }
+
+    // Step 2: Run beforeSave hooks (only for create/update)
+    if (operation === 'create' || operation === 'update') {
+      await runHooksForKey(chain, 'beforeSave', doc, ctx);
+    }
+
+    // Step 3: Run operation-specific before hooks (e.g. beforeCreate)
+    await runHooksForKey(chain, beforeHookKey, doc, ctx);
+
+    // Step 4: Execute the actual database operation
+    const txResult = await execute(doc, trx);
+
+    // Step 5: Run operation-specific after hooks (e.g. afterCreate)
+    await runHooksForKey(chain, afterHookKey, txResult, ctx);
+
+    return txResult;
+  });
+
+  // Step 6: Run afterSave hooks OUTSIDE the transaction (data already committed)
+  if (operation === 'create' || operation === 'update') {
+    const ctx: HookContext = createHookContext({
+      trx: db,
+      schema,
+      auth,
+      eventBus,
+      serviceRegistry,
+      config,
+    });
+    await runHooksForKey(chain, 'afterSave', result, ctx);
+  }
+
+  return result;
+}
+
+// --- Helpers ---
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** Run all synchronous validate hooks in the chain. */
+function runValidators(chain: HookChain, doc: HookDocument): void {
+  for (const entry of chain.entries) {
+    if (entry.hooks.validate) {
+      entry.hooks.validate(doc);
+    }
+  }
+}
+
+/** Run all hooks for a given key across the chain entries. */
+async function runHooksForKey(
+  chain: HookChain,
+  key: keyof HooksConfig,
+  doc: HookDocument,
+  ctx: HookContext,
+): Promise<void> {
+  for (const entry of chain.entries) {
+    const hook = entry.hooks[key] as ((doc: HookDocument, ctx: any) => Promise<void>) | undefined;
+    if (hook) {
+      await hook(doc, ctx);
+    }
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,10 @@
+export { HookRegistry } from './registry.js';
+export { ValidationError } from './errors.js';
+export { executeHookPipeline } from './executor.js';
+export { createHookContext } from './context.js';
+export {
+  withHooksCreate,
+  withHooksUpdate,
+  withHooksDelete,
+} from './middleware.js';
+export type { HookChain, HookEntry, HookLifecycle, HookContext, HookDocument } from './types.js';

package/src/hooks/middleware.ts

@@ -0,0 +1,220 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { Kysely } from 'kysely';
+import type { ResolvedModel } from '../schema/types.js';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { HookRegistry } from './registry.js';
+import type { HookDocument } from './types.js';
+import type { ServiceRegistry } from '../services/registry.js';
+import type { EventBus } from '../events/bus.js';
+import { executeHookPipeline, type HookOperation } from './executor.js';
+import { ValidationError } from './errors.js';
+import { getAuthContext } from '../auth/session.js';
+import { validateFields } from '../validation/field-validator.js';
+import { assertOwnership } from '../helpers/assert-ownership.js';
+import { stampCreate, stampUpdate } from '../helpers/stamping.js';
+import { findMissingRequiredFields } from '../helpers/validation.js';
+import { BadRequestError, NotFoundError } from '../errors.js';
+import type { ModelOps } from '../model-api/types.js';
+import { ModelQueryBuilder } from '../model-api/query-builder.js';
+
+// --- Types ---
+
+interface WithHooksContext {
+  model: ResolvedModel;
+  registry: SchemaRegistry;
+  db: Kysely<any>;
+  ops: ModelOps;
+  hookRegistry: HookRegistry;
+  serviceRegistry?: ServiceRegistry;
+  eventBus?: EventBus;
+  config?: Record<string, unknown>;
+}
+
+// --- Shared helpers (internal) ---
+
+function parseRequestBody(request: FastifyRequest): Record<string, unknown> {
+  const body = request.body as Record<string, unknown> | undefined;
+  if (!body || typeof body !== 'object') {
+    throw new BadRequestError('VALIDATION_ERROR', 'Request body is required');
+  }
+  return body;
+}
+
+async function findRecordOrNotFound(
+  ctx: WithHooksContext,
+  id: string,
+): Promise<Record<string, unknown>> {
+  const record = await new ModelQueryBuilder(ctx.ops, ctx.model, ctx.registry)
+    .filter({ id })
+    .first();
+
+  if (!record) {
+    throw new NotFoundError(`Record not found: ${id}`);
+  }
+  return record;
+}
+
+function handleHookError(err: unknown): never {
+  if (err instanceof ValidationError) {
+    throw new BadRequestError(err.code, err.message, err.field ? { field: err.field } : undefined);
+  }
+  if (err instanceof Error) {
+    throw new BadRequestError('VALIDATION_ERROR', err.message);
+  }
+  throw err;
+}
+
+function buildPipelineOptions(
+  ctx: WithHooksContext,
+  operation: HookOperation,
+  doc: HookDocument,
+  auth: any,
+  execute: (doc: HookDocument, trx: Kysely<unknown>) => Promise<HookDocument>,
+) {
+  return {
+    model: ctx.model.qualifiedName,
+    operation,
+    chain: ctx.hookRegistry.getChain(ctx.model.qualifiedName)!,
+    doc,
+    db: ctx.db,
+    schema: ctx.registry,
+    auth,
+    eventBus: ctx.eventBus,
+    serviceRegistry: ctx.serviceRegistry,
+    config: ctx.config,
+    execute,
+  };
+}
+
+// --- Exported middleware factories ---
+
+export function withHooksCreate(ctx: WithHooksContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const body = parseRequestBody(request);
+
+    const missingFields = findMissingRequiredFields(ctx.model, body);
+    if (missingFields.length > 0) {
+      throw new BadRequestError(
+        'VALIDATION_ERROR',
+        `Missing required fields: ${missingFields.join(', ')}`,
+        missingFields,
+      );
+    }
+
+    const fieldViolations = validateFields(ctx.model, body, 'create');
+    if (fieldViolations.length > 0) {
+      throw new BadRequestError(
+        'VALIDATION_ERROR',
+        fieldViolations.map((v) => v.message).join('; '),
+        fieldViolations,
+      );
+    }
+
+    const auth = getAuthContext(request);
+    stampCreate(body, ctx.model, auth);
+
+    const chain = ctx.hookRegistry.getChain(ctx.model.qualifiedName);
+    if (!chain) {
+      const record = await ctx.ops.create(body, auth);
+      return reply.status(201).send({ data: record });
+    }
+
+    try {
+      const result = await executeHookPipeline(
+        buildPipelineOptions(ctx, 'create', body as HookDocument, auth, async (doc, trx) => {
+          const txOps = ctx.ops.withTransaction!(trx);
+          return txOps.create(doc) as Promise<HookDocument>;
+        }),
+      );
+      return reply.status(201).send({ data: result });
+    } catch (err: unknown) {
+      return handleHookError(err);
+    }
+  };
+}
+
+export function withHooksUpdate(ctx: WithHooksContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const { id } = request.params as { id: string };
+    const body = parseRequestBody(request);
+
+    await findRecordOrNotFound(ctx, id);
+
+    const fieldViolations = validateFields(ctx.model, body, 'update');
+    if (fieldViolations.length > 0) {
+      throw new BadRequestError(
+        'VALIDATION_ERROR',
+        fieldViolations.map((v) => v.message).join('; '),
+        fieldViolations,
+      );
+    }
+
+    const authContext = getAuthContext(request);
+    const existing = await findRecordOrNotFound(ctx, id);
+    assertOwnership(authContext.permissions, ctx.model, existing, authContext.user?.id, 'write');
+
+    stampUpdate(body, ctx.model, authContext);
+
+    const chain = ctx.hookRegistry.getChain(ctx.model.qualifiedName);
+    if (!chain) {
+      const record = await ctx.ops.update(id, body, authContext);
+      return reply.send({ data: record });
+    }
+
+    try {
+      const result = await executeHookPipeline(
+        buildPipelineOptions(
+          ctx,
+          'update',
+          { ...body, id } as HookDocument,
+          authContext,
+          async (doc, trx) => {
+            const { id: docId, ...data } = doc;
+            const txOps = ctx.ops.withTransaction!(trx);
+            return txOps.update(docId as string, data) as Promise<HookDocument>;
+          },
+        ),
+      );
+      return reply.send({ data: result });
+    } catch (err: unknown) {
+      return handleHookError(err);
+    }
+  };
+}
+
+export function withHooksDelete(ctx: WithHooksContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const { id } = request.params as { id: string };
+
+    const existing = await findRecordOrNotFound(ctx, id);
+
+    const authContext = getAuthContext(request);
+    assertOwnership(authContext.permissions, ctx.model, existing, authContext.user?.id, 'delete');
+
+    const chain = ctx.hookRegistry.getChain(ctx.model.qualifiedName);
+    if (!chain) {
+      await ctx.ops.delete(id, authContext);
+      return reply.status(204).send();
+    }
+
+    try {
+      await executeHookPipeline(
+        buildPipelineOptions(
+          ctx,
+          'delete',
+          existing as HookDocument,
+          authContext,
+          async (doc, trx) => {
+            const txOps = ctx.ops.withTransaction!(trx);
+            await txOps.delete(doc.id as string);
+            return doc;
+          },
+        ),
+      );
+      return reply.status(204).send();
+    } catch (err: unknown) {
+      return handleHookError(err);
+    }
+  };
+}

package/src/hooks/registry.ts

@@ -0,0 +1,20 @@
+import type { HooksConfig } from '@rangka/shared';
+import type { HookChain } from './types.js';
+
+export class HookRegistry {
+  private chains: Map<string, HookChain> = new Map();
+
+  register(model: string, hooks: HooksConfig, source: string): void {
+    const chain = this.chains.get(model) ?? { entries: [] };
+    chain.entries.push({ hooks, source });
+    this.chains.set(model, chain);
+  }
+
+  getChain(model: string): HookChain | undefined {
+    return this.chains.get(model);
+  }
+
+  hasHooks(model: string): boolean {
+    return this.chains.has(model);
+  }
+}

package/src/hooks/types.ts

@@ -0,0 +1,32 @@
+import type {
+  HooksConfig,
+  HookDocument,
+  ValidateHook,
+  BeforeHook,
+  AfterHook,
+  FrameworkContext,
+} from '@rangka/shared';
+
+export type HookLifecycle =
+  | 'validate'
+  | 'beforeSave'
+  | 'afterSave'
+  | 'beforeCreate'
+  | 'afterCreate'
+  | 'beforeUpdate'
+  | 'afterUpdate'
+  | 'beforeDelete'
+  | 'afterDelete';
+
+export interface HookEntry {
+  hooks: HooksConfig;
+  source: string;
+}
+
+export interface HookChain {
+  entries: HookEntry[];
+}
+
+export type HookContext = FrameworkContext;
+
+export type { HooksConfig, HookDocument, ValidateHook, BeforeHook, AfterHook };

package/src/index.ts

@@ -0,0 +1,172 @@
+export { boot } from './boot/index.js';
+export type { BootOptions, BootResult } from './boot/index.js';
+export { SchemaRegistry } from './schema/registry.js';
+export { loadSchemas } from './boot/schema-loader.js';
+export type { SchemaLoadResult } from './boot/schema-loader.js';
+export { mergeSchemas } from './boot/schema-merger.js';
+export type { MergeResult } from './boot/schema-merger.js';
+export type {
+  ResolvedModel,
+  ResolvedField,
+  FieldProvenance,
+  ModelRelationship,
+  ExtensionSource,
+} from './schema/types.js';
+export type { RangkaPackageInfo, DiscoverySource, DiscoveredApp } from './boot/types.js';
+export {
+  SchemaConflictError,
+  MissingDependencyError,
+  CircularDependencyError,
+} from './boot/types.js';
+export {
+  AppError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+} from './errors.js';
+export { NodeModulesDiscoverySource, MemoryDiscoverySource } from './boot/discovery.js';
+export { ProjectScanner } from './boot/project-scanner.js';
+export type { ProjectScanResult } from './boot/project-scanner.js';
+export { DatabaseClient } from './db/client.js';
+export type { DatabaseClientConfig } from './db/client.js';
+export type {
+  ColumnDefinition,
+  TableDefinition,
+  IndexDefinition,
+  ForeignKeyDefinition,
+  DesiredState,
+  ActualState,
+  DdlOperation,
+} from './db/types.js';
+export { mapFieldsToColumns, modelToTableName } from './db/field-mapper.js';
+export { SchemaToDesired } from './db/desired-state.js';
+export { DiffEngine } from './db/diff-engine.js';
+export { introspect } from './db/introspect.js';
+export { autoSync } from './db/auto-sync.js';
+export type { DdlOperation as CoreDdlOperation } from './db/types.js';
+export { createServer } from './api/server.js';
+export { QueryParser, QueryValidationError } from './api/query-parser.js';
+export { generateRoutes } from './api/route-generator.js';
+export type { ServerConfig, ApiDefinition } from './api/types.js';
+export { defineApi, defineRoles, defineConfig } from '@rangka/shared';
+export type { RangkaConfig } from '@rangka/shared';
+
+// Auth & Permissions
+export {
+  PermissionRegistry,
+  DuplicateRoleError,
+  RoleInheritanceCycleError,
+} from './auth/permission-registry.js';
+export {
+  createAuthHook,
+  getAuthContext,
+  createSessionHandler,
+  deleteSessionHandler,
+  regenerateSessionToken,
+  generateToken,
+} from './auth/session.js';
+export { createModelPermissionGuard } from './auth/model-permissions.js';
+export { createScopeHook, createScopeWriteGuard, applyScopeFiltersToQuery } from './auth/scopes.js';
+export { ScopeRegistry, ScopeResolutionError } from './auth/scope-registry.js';
+export type { ResolvedScope, ModelScopeBinding } from './auth/scope-registry.js';
+export {
+  createFieldWriteGuard,
+  createFieldStripHook,
+  resolveFieldPermissions,
+} from './auth/field-permissions.js';
+export { debugPermissions, formatDebugResult } from './auth/debug.js';
+export { getCoreModels, getCoreApp } from './auth/core-module.js';
+export { coreSchemas } from './auth/core-models.js';
+export { seedCoreData } from './auth/seed.js';
+export { hashPassword, verifyPassword } from './auth/password.js';
+export type {
+  AuthUser,
+  AuthSession,
+  RequestContext,
+  ScopeFilter,
+  ResolvedPermissions,
+  RegisteredRole,
+} from './auth/types.js';
+
+// Hooks
+export { HookRegistry } from './hooks/registry.js';
+export { ValidationError } from './hooks/errors.js';
+export { executeHookPipeline } from './hooks/executor.js';
+export { createHookContext } from './hooks/context.js';
+export type {
+  HookChain,
+  HookEntry,
+  HookLifecycle,
+  HookContext,
+  HookDocument,
+} from './hooks/types.js';
+
+// Validation
+export { validateFields } from './validation/field-validator.js';
+export type { FieldViolation } from './validation/field-validator.js';
+
+// Jobs & Queue
+export { JobRegistry } from './jobs/registry.js';
+export { enqueue } from './jobs/enqueue.js';
+export { JobWorker } from './jobs/worker.js';
+export { ScheduleManager } from './jobs/scheduler.js';
+export { getJobTables } from './jobs/tables.js';
+export type {
+  JobRecord,
+  DeadLetterRecord,
+  ScheduledJobRecord,
+  JobState,
+  BackoffStrategy,
+  JobWorkerConfig,
+  RegisteredJob,
+  EnqueueOptions,
+} from './jobs/types.js';
+
+// Events
+export { EventBus } from './events/bus.js';
+export type { EventListener, EventBusConfig } from './events/types.js';
+
+// Services
+export {
+  ServiceRegistry,
+  ServiceCircularDependencyError,
+  ServiceNotFoundError,
+  DuplicateServiceError,
+} from './services/registry.js';
+export type {
+  ServiceDefinition,
+  ServiceFactory,
+  ServiceInstance,
+  ServiceDependency,
+  ServiceContext,
+} from './services/types.js';
+
+// Context
+export { createFrameworkContext, createRequestContext } from './context.js';
+export type { FrameworkContextOptions, RequestScopedContextOptions } from './context.js';
+
+// Fixtures
+export { FixtureRegistry } from './fixtures/registry.js';
+export { loadFixtures } from './fixtures/loader.js';
+export type {
+  FixtureDefinition,
+  FixtureRef,
+  FixtureRecord,
+  FixtureStatus,
+  FixtureLoadResult,
+  RegisteredFixture,
+} from './fixtures/types.js';
+
+// Audit Log
+export { getAuditTables } from './audit/tables.js';
+export { recordAudit, getAuditHistory } from './audit/record.js';
+export type { AuditAction, AuditChange, AuditLogRecord, AuditOptions } from './audit/types.js';
+
+// Widgets
+export { WidgetRegistry } from './widgets/widget-registry.js';
+export { validatePageBody } from './widgets/slot-validator.js';
+export type { SlotValidationError } from './widgets/slot-validator.js';
+
+// Coercion helpers
+export { toBool, toInt, isNil, toCount } from './helpers/coerce.js';