@cosmicdrift/kumiko-framework 0.1.0

package/src/engine/build-app-schema.ts

@@ -0,0 +1,125 @@
+// Erzeugt aus einer Server-Registry das client-safe AppSchema das die
+// Browser-Renderer-Pipeline konsumiert. Genauer Zweck: dev-server kann
+// die ganze hand-geschriebene `clientSchema`-Spiegelung abschaffen, der
+// Server schickt einfach das aufgelöste AppSchema beim Boot mit.
+//
+// JSON-Safety: Wir projezieren explizit auf eine Whitelist statt
+// JSON.stringify-roundtripping. Functions würden silent gedroppt und
+// Zod-Schemas (v4 hat .toJSON, aber emittiert ein _zod-Envelope) würden
+// als komische Ghost-Properties auftauchen. Das hier ist ein bewusster
+// Vertrag: was die Browser-Renderer-Pipeline liest, taucht hier auf.
+// Neue Browser-needed-Fields müssen explizit erweitert werden.
+//
+// Aktuell projeziert (Stand 2026-04-25):
+//   Entity:    { table?, fields: { type, required?, sortable?, default? } }
+//   Screen:    verbatim (ScreenDefinition ist von Haus aus JSON-safe —
+//              custom-screens haben keine functions, layout/columns/etc.
+//              sind plain literals)
+//   Nav:       verbatim (NavDefinition ist nur strings + literals)
+//   Workspace: verbatim definition + getWorkspaceNavs() von der Registry
+//
+// Feature-Toggles: BISHER NICHT GEFILTERT. Wenn ein Feature über die
+// feature-toggles-bundled-feature global deaktiviert ist, erscheint es
+// trotzdem im AppSchema. Reason: die Toggle-Auflösung lebt im pipeline-
+// dispatcher, nicht in der Registry, und wir haben hier keinen TenantDb-
+// Kontext um sie zu lesen. TODO wenn das ein realer Use-Case wird:
+// `effectiveFeatures` Argument annehmen und über alle iterations filtern.
+
+import type { AppSchema, EntityDefinition, FeatureSchema, WorkspaceSchema } from "../ui-types";
+import type { Registry } from "./types/feature";
+import type { FieldDefinition } from "./types/fields";
+
+export function buildAppSchema(registry: Registry): AppSchema {
+  const features: FeatureSchema[] = [];
+  for (const [featureName, feature] of registry.features) {
+    const navs = Object.values(feature.navs);
+    const featureSchema: FeatureSchema = {
+      featureName,
+      entities: projectEntities(feature.entities),
+      screens: Object.values(feature.screens),
+      ...(navs.length > 0 && { navs }),
+    };
+    features.push(featureSchema);
+  }
+
+  // Workspaces: getAllWorkspaces() liefert mit QUALIFIZIERTEN ids (das
+  // schreibt die Registry beim Store-Overwrite ein). Die Browser-
+  // Renderer erwartet aber kurze ids (matcht gegen URL-Segment, gegen
+  // navigate({ workspaceId })). Wir gehen direkt durch `feature.workspaces`
+  // — dort sind die ids noch in der Autor-Form (short) — und ziehen die
+  // pre-resolved navMembers aus der Registry.
+  const workspaces: WorkspaceSchema[] = [];
+  for (const [featureName, feature] of registry.features) {
+    for (const [shortId, definition] of Object.entries(feature.workspaces)) {
+      const qualified = `${featureName}:workspace:${shortId}`;
+      workspaces.push({
+        definition: { ...definition, id: shortId },
+        navMembers: registry.getWorkspaceNavs(qualified),
+      });
+    }
+  }
+
+  return {
+    features,
+    ...(workspaces.length > 0 && { workspaces }),
+  };
+}
+
+function projectEntities(
+  entities: Readonly<Record<string, EntityDefinition>>,
+): Readonly<Record<string, EntityDefinition>> {
+  const out: Record<string, EntityDefinition> = {};
+  for (const [name, entity] of Object.entries(entities)) {
+    out[name] = projectEntity(entity);
+  }
+  return out;
+}
+
+// EntityDefinition ist eine Discriminated-Union an Field-Types — wir
+// kennen alle JSON-safe Properties pro Field-Type. Statt jede Variante
+// einzeln auszuhandeln, walken wir die Field-Map und filtern auf die
+// Whitelist. Was nicht durchkommt: Server-only-runtime wie ZodValidate-
+// Functions, Computed-Functions, Default-Functions.
+function projectEntity(entity: EntityDefinition): EntityDefinition {
+  const fieldsOut: Record<string, FieldDefinition> = {};
+  for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+    fieldsOut[fieldName] = projectField(fieldDef);
+  }
+  // EntityDefinition akzeptiert idType/access/searchWeight als optional —
+  // wir lassen die weg weil der Browser-Renderer sie nicht liest. `table`
+  // schicken wir mit, falls Apps `entity.table` direkt referenzieren.
+  // Kein Cast nötig: alle weggelassenen Felder sind `?`-optional.
+  return {
+    fields: fieldsOut,
+    ...(typeof entity.table === "string" && { table: entity.table }),
+  };
+}
+
+// Whitelist pro Field. `default` darf nur durch wenn Literal (string/
+// number/boolean/null) — auch wenn die FieldDefinition-Types „default"
+// nur als Literal typisieren, hat das Sample-Pattern
+// `as unknown as EntityDefinition` Authorinnen schon Function-Defaults
+// reinschmuggeln lassen. Diese Defense-in-Depth fängt sie ab BEVOR
+// JSON.stringify sie in der Browser-Injection-Pipeline droppt.
+//
+// Cast am Exit `as FieldDefinition`: type-system-wise erfüllt unsere
+// Out-Map die Discriminated-Union nur mit unverengtem `type`-String —
+// der Cast bridged die Variant-Inferenz, die TS aus einem Generic
+// Record nicht zurückrechnet.
+function projectField(fieldDef: FieldDefinition): FieldDefinition {
+  const def = fieldDef as Record<string, unknown>; // @cast-boundary schema-walk
+  const out: Record<string, unknown> = {};
+  if (typeof def["type"] === "string") out["type"] = def["type"];
+  if (typeof def["required"] === "boolean") out["required"] = def["required"];
+  if (typeof def["sortable"] === "boolean") out["sortable"] = def["sortable"];
+  if (isLiteral(def["default"])) out["default"] = def["default"];
+  // Select: options-Liste ist plain JSON, durchschicken.
+  if (Array.isArray(def["options"])) out["options"] = def["options"];
+  return out as FieldDefinition;
+}
+
+function isLiteral(value: unknown): boolean {
+  if (value === null) return true;
+  const t = typeof value;
+  return t === "string" || t === "number" || t === "boolean";
+}

package/src/engine/config-helpers.ts

@@ -0,0 +1,115 @@
+import type { ConfigScope } from "./constants";
+import type {
+  ConfigBounds,
+  ConfigComputedFn,
+  ConfigKeyDefinition,
+  ConfigKeyType,
+  ConfigValue,
+} from "./types";
+
+// --- Access Presets ---
+
+export const access = {
+  all: ["all"] as readonly string[],
+  admin: ["Admin", "SystemAdmin"] as readonly string[],
+  systemAdmin: ["SystemAdmin"] as readonly string[],
+  system: ["system"] as readonly string[],
+  // system + SystemAdmin — use for field-access on identity columns that
+  // framework auth code (SYSTEM_USER) writes during login/registration, but
+  // that a SystemAdmin should also be able to fix manually.
+  privileged: ["system", "SystemAdmin"] as readonly string[],
+  // Any signed-in user role. Use on authenticated-but-not-privileged handlers
+  // (change-password, logout, me-style queries). Does NOT include "system"
+  // since an unauthenticated system call shouldn't be able to hit these.
+  authenticated: ["User", "Admin", "SystemAdmin"] as readonly string[],
+  // Unauthenticated callers reaching public endpoints (server must opt in
+  // via `anonymousAccess`). Combine with authenticated roles when an
+  // endpoint should serve both — e.g. `roles: ["anonymous", "customer"]`
+  // for a product-listing that personalises when a session is present.
+  anonymous: ["anonymous"] as readonly string[],
+  roles: (...roles: string[]): readonly string[] => roles,
+} as const;
+
+// --- Config Key Options ---
+
+// Generic so `default` narrows per type-tag — without it,
+// `createUserConfig("boolean", { default: 19 })` would compile.
+//
+// `bounds` is conditional: only `type="number"` admits it. For any other
+// type-tag the field is `never`, so `createTenantConfig("text", { bounds })`
+// fails at the call site. Matches the same pattern as `default`.
+//
+// `computed` is a fallback-resolver the registry calls when no row + no
+// app-override exists — used for plan-based limits (see
+// configuration-layers.md, "Frage 3: Hängt Geld dran?").
+//
+// `allowPerRequest` is conditional against `text`: text keys can never
+// opt in to per-request overrides (XSS/SQL/Shell risk). For other types
+// it's a plain boolean opt-in consumed by resolveConfigOrParam.
+type ConfigKeyOptions<T extends ConfigKeyType> = {
+  write?: readonly string[];
+  read?: readonly string[];
+  default?: ConfigValue<T>;
+  encrypted?: boolean;
+  options?: readonly string[]; // for select type
+  bounds?: T extends "number" ? ConfigBounds : never;
+  computed?: ConfigComputedFn<T>;
+  allowPerRequest?: T extends "text" ? never : boolean;
+};
+
+// --- Scope Defaults ---
+
+const SCOPE_DEFAULTS: Record<ConfigScope, { write: readonly string[]; read: readonly string[] }> = {
+  tenant: { write: access.admin, read: access.all },
+  system: { write: access.system, read: access.admin },
+  user: { write: access.all, read: access.all },
+};
+
+// --- Factory ---
+
+function createConfigKey<T extends ConfigKeyType>(
+  scope: ConfigScope,
+  type: T,
+  opts: ConfigKeyOptions<T> = {},
+): ConfigKeyDefinition<T> {
+  const defaults = SCOPE_DEFAULTS[scope];
+  return {
+    type,
+    scope,
+    access: {
+      write: opts.write ?? defaults.write,
+      read: opts.read ?? defaults.read,
+    },
+    default: opts.default,
+    ...(opts.encrypted ? { encrypted: true } : {}),
+    ...(opts.options ? { options: opts.options } : {}),
+    bounds: opts.bounds as ConfigBounds | undefined,
+    computed: opts.computed,
+    ...(opts.allowPerRequest === true ? { allowPerRequest: true } : {}),
+  };
+}
+
+// --- Public API ---
+// Generic on the type-tag so `r.config({keys})` can propagate it into the
+// returned `ConfigKeyHandle<T>` — that's what narrows `ctx.config(handle)`.
+
+export function createTenantConfig<T extends ConfigKeyType>(
+  type: T,
+  opts?: ConfigKeyOptions<T>,
+): ConfigKeyDefinition<T> {
+  return createConfigKey("tenant", type, opts);
+}
+
+export function createSystemConfig<T extends ConfigKeyType>(
+  type: T,
+  opts?: ConfigKeyOptions<T>,
+): ConfigKeyDefinition<T> {
+  return createConfigKey("system", type, opts);
+}
+
+export function createUserConfig<T extends ConfigKeyType>(
+  type: T,
+  opts?: ConfigKeyOptions<T>,
+): ConfigKeyDefinition<T> {
+  return createConfigKey("user", type, opts);
+}

package/src/engine/constants.ts

@@ -0,0 +1,85 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+// All framework constants as `as const` objects with inferred union types.
+// No enums — only const objects + typeof inference.
+
+// Error codes — the canonical list lives on the KumikoError subclasses in
+// `errors/classes.ts`. Features that need to surface a feature-specific reason
+// attach it under `details.reason` on the relevant Kumiko error class.
+
+// --- System Hook Names ---
+
+export const SystemHookNames = {
+  cascadeDelete: "system:hook:cascade-delete",
+} as const;
+
+export type SystemHookName = (typeof SystemHookNames)[keyof typeof SystemHookNames];
+
+// --- System Hook Priorities ---
+
+export const SystemHookPriorities = {
+  cascadeDelete: 500,
+} as const;
+
+// --- Message Kinds ---
+
+export const MessageKind = {
+  write: "write",
+  query: "query",
+  command: "command",
+  shared: "shared",
+  broadcast: "broadcast",
+} as const;
+
+export type MessageKind = (typeof MessageKind)[keyof typeof MessageKind];
+
+// --- Lifecycle Hook Types ---
+
+export const LifecycleHookTypes = {
+  preSave: "preSave",
+  postSave: "postSave",
+  preDelete: "preDelete",
+  postDelete: "postDelete",
+  preQuery: "preQuery",
+} as const;
+
+export type LifecycleHookType = (typeof LifecycleHookTypes)[keyof typeof LifecycleHookTypes];
+
+// --- Config Scopes ---
+
+export const ConfigScopes = {
+  system: "system",
+  tenant: "tenant",
+  user: "user",
+} as const;
+
+export type ConfigScope = (typeof ConfigScopes)[keyof typeof ConfigScopes];
+
+// --- On Delete Strategies ---
+
+export const OnDeleteStrategies = {
+  cascade: "cascade",
+  restrict: "restrict",
+  setNull: "setNull",
+  nothing: "nothing",
+} as const;
+
+export type OnDeleteStrategy = (typeof OnDeleteStrategies)[keyof typeof OnDeleteStrategies];
+
+// --- Concurrency Modes ---
+
+export const ConcurrencyModes = {
+  parallel: "parallel",
+  skip: "skip",
+  replace: "replace",
+  sequential: "sequential",
+  debounce: "debounce",
+} as const;
+
+export type ConcurrencyMode = (typeof ConcurrencyModes)[keyof typeof ConcurrencyModes];
+
+// --- SSE Channels ---
+
+export function tenantChannel(tenantId: TenantId): string {
+  return `tenant:${tenantId}`;
+}

package/src/engine/create-app.ts

@@ -0,0 +1,98 @@
+import { validateBoot } from "./boot-validator";
+import { createRegistry } from "./registry";
+import type { FeatureDefinition, Registry } from "./types";
+import { DEFAULT_CURRENCIES } from "./types";
+
+export type AppConfig = {
+  roles: readonly string[];
+  features: readonly FeatureDefinition[];
+  softDelete?: boolean; // Global default for all entities (default: true)
+  currencies?: readonly string[]; // Extends DEFAULT_CURRENCIES
+};
+
+export type App = {
+  registry: Registry;
+  roles: readonly string[];
+  softDeleteDefault: boolean;
+  currencies: readonly string[];
+};
+
+export function createApp(config: AppConfig): App {
+  const validRoles = new Set(config.roles);
+
+  // "system" is reserved for SYSTEM_USER — cannot be used as an app role
+  if (validRoles.has("system")) {
+    throw new Error('Role "system" is reserved for SYSTEM_USER and cannot be used as an app role');
+  }
+
+  // Special roles that don't need to be in the app's role list
+  const systemRoles = new Set(["all", "system"]);
+
+  // Validate all roles referenced by features exist in app-defined roles.
+  // openToAll access has no role list — nothing to validate there.
+  for (const feature of config.features) {
+    for (const handler of Object.values(feature.writeHandlers)) {
+      if (handler.access && "roles" in handler.access) {
+        for (const role of handler.access.roles) {
+          if (!validRoles.has(role)) {
+            throw new Error(
+              `Unknown role "${role}" in write handler "${handler.name}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`,
+            );
+          }
+        }
+      }
+    }
+    for (const handler of Object.values(feature.queryHandlers)) {
+      if (handler.access && "roles" in handler.access) {
+        for (const role of handler.access.roles) {
+          if (!validRoles.has(role)) {
+            throw new Error(
+              `Unknown role "${role}" in query handler "${handler.name}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`,
+            );
+          }
+        }
+      }
+    }
+    for (const [key, keyDef] of Object.entries(feature.configKeys)) {
+      for (const role of [...keyDef.access.read, ...keyDef.access.write]) {
+        if (!systemRoles.has(role) && !validRoles.has(role)) {
+          throw new Error(
+            `Unknown role "${role}" in config key "${feature.name}.${key}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`,
+          );
+        }
+      }
+    }
+  }
+
+  const softDeleteDefault = config.softDelete ?? true;
+
+  // Merge default + custom currencies, deduplicate
+  const currencies = [...new Set([...DEFAULT_CURRENCIES, ...(config.currencies ?? [])])];
+
+  // Validate defaultCurrency on entities that have money fields
+  for (const feature of config.features) {
+    for (const [entityName, entity] of Object.entries(feature.entities)) {
+      const hasMoneyField = Object.values(entity.fields).some((f) => f.type === "money");
+      if (entity.defaultCurrency && !currencies.includes(entity.defaultCurrency)) {
+        throw new Error(
+          `Entity "${entityName}" in feature "${feature.name}" has defaultCurrency "${entity.defaultCurrency}" which is not in the currencies list. Available: ${currencies.join(", ")}`,
+        );
+      }
+      if (hasMoneyField && !entity.defaultCurrency) {
+        throw new Error(
+          `Entity "${entityName}" in feature "${feature.name}" has money fields but no defaultCurrency. Set defaultCurrency on the entity definition.`,
+        );
+      }
+    }
+  }
+
+  // Run boot-time validation before creating registry
+  validateBoot(config.features);
+
+  return {
+    registry: createRegistry(config.features),
+    roles: config.roles,
+    softDeleteDefault,
+    currencies,
+  };
+}