@cosmicdrift/kumiko-framework 0.1.0

package/src/time/tz-context.ts

@@ -0,0 +1,107 @@
+// ctx.tz — die Feature-Code-API für TZ-Operationen.
+//
+// Eine konsistente Form für jeden Date/Time-Bedarf im Handler-Code:
+//   - "Jetzt als UTC-Instant"        → ctx.tz.now()
+//   - "Heute in Tenant-TZ"           → ctx.tz.today(ctx.tz.tenant)
+//   - "Wall-Clock parsen"            → ctx.tz.parse("2026-04-03T10:00", "Europe/Lisbon")
+//   - "ZonedDateTime → JSON-Pair"    → ctx.tz.toLocatedJson(zdt)
+//   - "JSON-Pair → ZonedDateTime"    → ctx.tz.fromLocatedJson({ at, tz })
+//
+// Feature-Code soll NICHT mehr `new Date()` aufrufen — die Lint-Regel dafür
+// kommt in einer späteren Iteration, wenn alle existing usages migriert sind.
+//
+// `tenant` + `user` sind die TZ-Defaults für den aktuellen Request. Aktueller
+// Stand (Iteration 4): beide default auf "UTC" — sobald tenant.timezone +
+// user.timezone Felder existieren, lese ich sie aus dem Request-Context.
+// TODO(Iteration 6): aus tenant entity / user profile lesen.
+
+import { ensureTemporalPolyfill, getTemporal } from "./polyfill";
+
+// JSON-Form für Wall-Clock+TZ — siehe locatedTimestamp(name) Helper in
+// engine/factories.ts. Zwei Felder, idiotensicher.
+export type LocatedTimestampJson = {
+  /** Wall-Clock-ISO ohne Offset, z.B. "2026-04-03T10:00:00" */
+  readonly at: string;
+  /** IANA-Zone, z.B. "Europe/Lisbon" */
+  readonly tz: string;
+};
+
+export type TzContext = {
+  /** Default-TZ des Mandanten (aus tenant.timezone, default "UTC"). */
+  readonly tenant: string;
+  /** Anzeige-TZ des aktuellen Users (User-Profil-Override, fallback Tenant). */
+  readonly user: string;
+
+  /** Aktueller Moment als UTC-Instant. */
+  now(): Temporal.Instant;
+  /** Aktueller Moment als ZonedDateTime in der gewünschten Zone. */
+  nowIn(tz: string): Temporal.ZonedDateTime;
+
+  /** Heutiges Kalender-Datum in der gewünschten Zone. */
+  today(tz: string): Temporal.PlainDate;
+  /** Tagesgrenzen (00:00 bis 24:00 nächster Tag) als UTC-Instants — für DB-Range-Queries. */
+  todayRange(tz: string): { readonly start: Temporal.Instant; readonly end: Temporal.Instant };
+
+  /** Wall-Clock-String + IANA-Zone → ZonedDateTime. */
+  parse(wallClock: string, tz: string): Temporal.ZonedDateTime;
+
+  /** ZonedDateTime → UTC-Instant. */
+  toInstant(zdt: Temporal.ZonedDateTime): Temporal.Instant;
+
+  /** ZonedDateTime → JSON-Pair { at, tz } (API-Boundary). */
+  toLocatedJson(zdt: Temporal.ZonedDateTime): LocatedTimestampJson;
+
+  /** JSON-Pair { at, tz } → ZonedDateTime (Wall-Clock + IANA). */
+  fromLocatedJson(obj: LocatedTimestampJson): Temporal.ZonedDateTime;
+};
+
+export type TzContextOptions = {
+  /** Tenant-Default-TZ. Default "UTC" wenn nicht gesetzt. */
+  readonly tenant?: string;
+  /** User-Override. Default = tenant. */
+  readonly user?: string;
+};
+
+/**
+ * Factory: erzeugt einen TzContext für den aktuellen Request.
+ * Erwartet dass ensureTemporalPolyfill() bereits gelaufen ist (passiert beim
+ * Framework-Boot). Wenn nicht, wirft getTemporal() — kein silent failure.
+ */
+export function createTzContext(options: TzContextOptions = {}): TzContext {
+  const T = getTemporal();
+  const tenant = options.tenant ?? "UTC";
+  const user = options.user ?? tenant;
+
+  return {
+    tenant,
+    user,
+    now: () => T.Now.instant(),
+    nowIn: (tz: string) => T.Now.zonedDateTimeISO(tz),
+    today: (tz: string) => T.Now.plainDateISO(tz),
+    todayRange: (tz: string) => {
+      const today = T.Now.plainDateISO(tz);
+      const startZdt = today.toZonedDateTime({ timeZone: tz });
+      const endZdt = today.add({ days: 1 }).toZonedDateTime({ timeZone: tz });
+      return { start: startZdt.toInstant(), end: endZdt.toInstant() };
+    },
+    parse: (wallClock: string, tz: string) => T.PlainDateTime.from(wallClock).toZonedDateTime(tz),
+    toInstant: (zdt) => zdt.toInstant(),
+    toLocatedJson: (zdt) => ({
+      // Wall-Clock OHNE Offset (kein "Z", kein "+01:00") plus IANA-Name.
+      // .toPlainDateTime().toString() liefert "YYYY-MM-DDTHH:MM:SS[.fff]"
+      // ohne Offset — exakt unser Vertrag.
+      at: zdt.toPlainDateTime().toString(),
+      tz: zdt.timeZoneId,
+    }),
+    fromLocatedJson: (obj) => T.PlainDateTime.from(obj.at).toZonedDateTime(obj.tz),
+  };
+}
+
+/**
+ * Convenience: stellt sicher dass der Polyfill geladen ist UND erzeugt
+ * den TzContext in einem await. Bevorzugt verwenden in Boot-Code.
+ */
+export async function createTzContextAsync(options?: TzContextOptions): Promise<TzContext> {
+  await ensureTemporalPolyfill();
+  return createTzContext(options);
+}

package/src/ui-types/app-schema.ts

@@ -0,0 +1,57 @@
+// Client-safe Schema-Types. Wohnen in framework/ui-types statt renderer
+// damit der Server (createKumikoServer / buildAppSchema) sie produzieren
+// kann ohne renderer als Dependency zu ziehen. Renderer + Renderer-Web
+// re-exporten dieselben Symbole — Konsumenten merken den Umzug nicht.
+//
+// Pattern: Types fließen "downstream" (framework → renderer → renderer-
+// web), Runtime-Helpers (toAppSchema, isAppSchema) bleiben renderer-side
+// weil das die Layer ist die mit den AppSchemas zur Laufzeit arbeitet.
+
+import type { EntityDefinition } from "../engine/types/fields";
+import type { NavDefinition } from "../engine/types/nav";
+import type { ScreenDefinition } from "../engine/types/screen";
+import type { WorkspaceDefinition } from "../engine/types/workspace";
+
+export type FeatureSchema = {
+  readonly featureName: string;
+  readonly entities: Readonly<Record<string, EntityDefinition>>;
+  readonly screens: readonly ScreenDefinition[];
+  // Flat list; resolveNavigation builds the tree at render-time from
+  // the registry's indexes. Omitted when the app has no top-level nav.
+  readonly navs?: readonly NavDefinition[];
+  // Workspaces — Legacy-Slot für single-feature-Apps. Bevorzugt liegt
+  // workspaces auf der AppSchema-Ebene weil ihre navMembers regelmäßig
+  // Cross-Feature-Navs referenzieren (siehe AppSchema-Doc). Hier als
+  // Fallback erhalten damit alte clientSchema-Files (vor AppSchema)
+  // ohne Migration weiter laufen — toAppSchema() hebt die Liste hoch.
+  readonly workspaces?: readonly WorkspaceSchema[];
+};
+
+// Per-workspace projection of the engine's WorkspaceDefinition + the
+// pre-resolved member nav QNs. The shell renders the switcher from
+// `definition` and filters the nav tree using `navMembers`.
+export type WorkspaceSchema = {
+  readonly definition: WorkspaceDefinition;
+  // Nav QNs that belong to this workspace, in the order the engine
+  // resolved them (explicit r.workspace.nav first, then nav-self-assigned
+  // entries — deduped). Empty when no nav has been assigned.
+  readonly navMembers: readonly string[];
+};
+
+// App-level schema. Bündelt ein oder mehrere FeatureSchemas + die App-
+// weiten Workspaces. Sinn der Trennung: Workspaces aggregieren über
+// Feature-Grenzen (admin-Workspace zeigt navs aus mehreren Features), und
+// die navMembers-Liste enthält voll qualifizierte QNs die der Browser
+// gegen die jeweilige feature-spezifische `navs`-Liste auflöst.
+//
+// Backwards-Compat: createKumikoApp + die Layouts (DefaultAppShell,
+// WorkspaceShell) akzeptieren beides — `FeatureSchema` (single-feature,
+// historisch) und `AppSchema` (multi-feature). Ein `toAppSchema(input)`-
+// Adapter normalisiert intern, sodass die ganze inneren Renderer-Pipeline
+// nur noch AppSchema kennt.
+export type AppSchema = {
+  readonly features: readonly FeatureSchema[];
+  // Optional — Apps ohne Workspaces nutzen DefaultAppShell und sehen
+  // schlicht die NavTree aller Features.
+  readonly workspaces?: readonly WorkspaceSchema[];
+};

package/src/ui-types/index.ts

@@ -0,0 +1,65 @@
+// @runtime client
+//
+// Client-safe subset of engine types + the two normalize helpers. Split
+// out into its own subpath (`@cosmicdrift/kumiko-framework/ui-types`) so ui-core and
+// renderer packages can import without pulling node-only framework
+// internals (postgres, drizzle-kit, ioredis, bullmq, ...) into the
+// browser or Expo bundle through the main `./engine` barrel.
+//
+// The main `./engine` barrel re-exports `createApp`, `defineFeature`,
+// and other server-runtime factories. Even with `import type` on the
+// consumer side, some bundlers pull evaluation of the barrel, which
+// transitively reaches `pg` / `ioredis` / `tls`. This entry stays narrow:
+// types + the two pure-fn normalize helpers. No runtime imports of node
+// built-ins or of framework DB / pipeline modules.
+//
+// The `type` re-exports below still chain into files that contain
+// runtime code (fields.ts → ownership.ts → drizzle-orm; handlers.ts →
+// ioredis etc.). With `verbatimModuleSyntax: true` and `import type` on
+// every hop the bundler strips those; this file reaches only type-space.
+// When adding a symbol here, verify it's either a type or a pure
+// helper with no cross-module side-effects.
+
+export type { ParsedRefTarget } from "../engine/parse-ref-target";
+export { parseRefTarget } from "../engine/parse-ref-target";
+// Entity + field types. EntityDefinition is the canonical shape that
+// view-model builders iterate; FieldDefinition is the per-field union
+// (text, number, boolean, ...) they branch on. AccessRule is used by
+// resolveNavigation to gate entries by user roles.
+export type {
+  BooleanFieldDef,
+  DateFieldDef,
+  EntityDefinition,
+  FieldDefinition,
+  FileFieldDef,
+  FilesFieldDef,
+  ImageFieldDef,
+  ImagesFieldDef,
+  NumberFieldDef,
+  SelectFieldDef,
+  TextFieldDef,
+} from "../engine/types/fields";
+export type { AccessRule } from "../engine/types/handlers";
+export type { NavDefinition } from "../engine/types/nav";
+export type {
+  ActionFormScreenDefinition,
+  ConfigEditScreenDefinition,
+  CustomScreenDefinition,
+  CustomScreenRoute,
+  EditFieldSpec,
+  EditLayout,
+  EditSectionSpec,
+  EntityEditScreenDefinition,
+  EntityListScreenDefinition,
+  FieldCondition,
+  FieldRenderer,
+  ListColumnSpec,
+  PlatformComponent,
+  ScreenDefinition,
+  ScreenFilter,
+  ScreenFilterOp,
+  ScreenSlots,
+} from "../engine/types/screen";
+export { normalizeEditField, normalizeListColumn } from "../engine/types/screen";
+export type { WorkspaceDefinition } from "../engine/types/workspace";
+export type { AppSchema, FeatureSchema, WorkspaceSchema } from "./app-schema";

package/src/utils/__tests__/assert.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "vitest";
+import { assertUnreachable } from "../assert";
+
+describe("assertUnreachable", () => {
+  test("throws with the kind label and the offending value in the message", () => {
+    // Runtime path: the compile-time never-check is verified by tsc itself —
+    // this test just exercises the throw for a case where the union was
+    // extended without updating callers.
+    expect(() => {
+      // Simulating a future enum-extension where a call site forgot to handle
+      // the new member. The `as never` matches what a wrong-shape value would
+      // look like at runtime after escaping the compiler.
+      const rogue = "surprise" as unknown as never;
+      assertUnreachable(rogue, "status");
+    }).toThrow(/unhandled status: surprise/);
+  });
+});

package/src/utils/__tests__/env-parse.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "vitest";
+import { readPositiveIntEnv } from "../env-parse";
+
+describe("readPositiveIntEnv", () => {
+  test("returns undefined when the key is absent", () => {
+    expect(readPositiveIntEnv({}, "POOL_MAX")).toBeUndefined();
+  });
+
+  test("returns undefined when the value is the empty string", () => {
+    // Shell-quirk: `POOL_MAX=` in a .env yields "" — treat as "unset" so
+    // callers fall through to the framework default instead of throwing.
+    expect(readPositiveIntEnv({ POOL_MAX: "" }, "POOL_MAX")).toBeUndefined();
+  });
+
+  test("parses a valid non-negative integer", () => {
+    expect(readPositiveIntEnv({ POOL_MAX: "20" }, "POOL_MAX")).toBe(20);
+  });
+
+  test("accepts 0 (the framework sentinel for 'disable')", () => {
+    expect(readPositiveIntEnv({ POOL_MAX: "0" }, "POOL_MAX")).toBe(0);
+  });
+
+  test("throws on a negative number with the variable name + value in the message", () => {
+    expect(() => readPositiveIntEnv({ POOL_MAX: "-1" }, "POOL_MAX")).toThrow(
+      /POOL_MAX="-1" must be a non-negative integer/,
+    );
+  });
+
+  test("throws on a fractional number", () => {
+    expect(() => readPositiveIntEnv({ POOL_MAX: "1.5" }, "POOL_MAX")).toThrow(
+      /POOL_MAX="1.5" must be a non-negative integer/,
+    );
+  });
+
+  test("throws on non-numeric input", () => {
+    expect(() => readPositiveIntEnv({ POOL_MAX: "abc" }, "POOL_MAX")).toThrow(
+      /POOL_MAX="abc" must be a non-negative integer/,
+    );
+  });
+
+  test("throws on whitespace-only input (Number('   ') is 0 — but trim first)", () => {
+    // Number("   ") === 0, which would silently pass the non-negative-integer
+    // check. Verifying the current behavior: pure whitespace is parsed as 0
+    // because Number() coerces it. If this changes, the test forces a
+    // deliberate update rather than a silent drift.
+    expect(readPositiveIntEnv({ POOL_MAX: "   " }, "POOL_MAX")).toBe(0);
+  });
+
+  test("throws on Infinity", () => {
+    expect(() => readPositiveIntEnv({ POOL_MAX: "Infinity" }, "POOL_MAX")).toThrow(
+      /POOL_MAX="Infinity" must be a non-negative integer/,
+    );
+  });
+});

package/src/utils/assert.ts

@@ -0,0 +1,18 @@
+// Exhaustiveness-check helper for switch statements over union types.
+// Dropping a new member into the union triggers a compile-time error in
+// the call site unless a matching case is added — keeps switches honest
+// through future enum growth.
+//
+//   switch (status) {
+//     case "open": return ...;
+//     case "closed": return ...;
+//     default: assertUnreachable(status, "status");
+//   }
+//
+// The `never` parameter makes TS flag any code path that still has a
+// live value (e.g. a new union case was added and the switch missed it).
+// Runtime also throws so a production surprise surfaces loudly instead
+// of silently falling through.
+export function assertUnreachable(value: never, kind: string): never {
+  throw new Error(`[Kumiko] unhandled ${kind}: ${String(value)}`);
+}

package/src/utils/env-parse.ts

@@ -0,0 +1,16 @@
+// Strict env-var parsers. Misconfig at boot is loud: every helper throws
+// with the offending variable name + value so ops sees exactly what's
+// wrong instead of a cascading timeout downstream.
+
+export function readPositiveIntEnv(
+  env: Readonly<Record<string, string | undefined>>,
+  name: string,
+): number | undefined {
+  const raw = env[name];
+  if (raw === undefined || raw === "") return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) {
+    throw new Error(`[env] ${name}="${raw}" must be a non-negative integer`);
+  }
+  return n;
+}

package/src/utils/ids.ts

@@ -0,0 +1,16 @@
+import { v7 } from "uuid";
+
+// Non-secret identifiers for DB rows, event streams, correlation/request
+// IDs, SSE connections, distributed locks. UUIDv7: first 48 bits are a
+// Unix-ms timestamp, remaining 74 bits are random. Lexicographic order
+// matches chronological order, so B-Tree indexes stay dense on insert
+// and time-range queries ("events for stream X since T") read sequential
+// pages. Universal-safe — uses the `uuid` npm package, not `node:crypto`,
+// so the same call works in Bun, Node, Metro/RN, and Expo-Web bundles.
+//
+// Do NOT use this for security tokens (CSRF, session, API keys). The
+// timestamp prefix leaks creation time and shrinks unpredictable
+// entropy from 122 to 74 bits — use `generateToken` from api/tokens.ts.
+export function generateId(): string {
+  return v7();
+}

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export { assertUnreachable } from "./assert";
+export { readPositiveIntEnv } from "./env-parse";
+export { generateId } from "./ids";
+export { parseJsonOrThrow, parseJsonSafe } from "./safe-json";
+export { parseRoles } from "./serialization";

package/src/utils/safe-json.ts

@@ -0,0 +1,30 @@
+/**
+ * Safe JSON parsing — never let invalid input from Redis/DB/external systems
+ * crash the pipeline silently. Two variants for two different semantics:
+ *
+ * - parseJsonSafe(raw, fallback): for caches and idempotent reads. Corrupt
+ *   input is treated as "not there" (fallback returned). The caller continues
+ *   as if the cache missed.
+ * - parseJsonOrThrow(raw, context): for inputs where corruption is a real bug
+ *   (config values, job payloads, broker messages addressed to us). Throws
+ *   with a clear context message so the stack trace points to the boundary.
+ */
+
+export function parseJsonSafe<T>(raw: string, fallback: T): T {
+  try {
+    // @cast-boundary engine-bridge — generic parser-helper centralizes the cast
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export function parseJsonOrThrow<T>(raw: string, context: string): T {
+  try {
+    // @cast-boundary engine-bridge — generic parser-helper centralizes the cast
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Invalid JSON in ${context}: ${msg}`);
+  }
+}

package/src/utils/serialization.ts

@@ -0,0 +1,7 @@
+import { parseJsonSafe } from "./safe-json";
+
+export function parseRoles(raw: unknown): string[] {
+  if (typeof raw === "string") return parseJsonSafe<string[]>(raw, []);
+  if (Array.isArray(raw)) return raw;
+  return [];
+}