@cosmicdrift/kumiko-bundled-features 0.4.0 → 0.5.0

package/src/config/index.ts

@@ -1,3 +1,8 @@
+import type { DbConnection, EncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
+import { seedConfigValues } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { configValueEntity, configValuesTable } from "./table";
+
 export {
   CONFIG_FEATURE,
   ConfigErrors,
@@ -13,3 +18,15 @@ export {
 export type { AppConfigOverrides, ConfigResolver } from "./resolver";
 export { createConfigResolver, validateAppOverrides } from "./resolver";
 export { configValuesTable } from "./table";
+
+// Boot helper for runDevApp / runProdApp: pulls every ConfigSeedDef from
+// the registry and writes the matching system/tenant/user rows via the
+// event-store executor. Idempotent across boots — see config-seeding.md.
+export function seedAllConfigValues(
+  registry: Registry,
+  db: DbConnection,
+  encryption?: EncryptionProvider,
+): Promise<{ created: number; skipped: number }> {
+  const seeds = registry.getAllConfigSeeds();
+  return seedConfigValues(seeds, configValuesTable, configValueEntity, registry, db, encryption);
+}

package/src/config/resolver.ts

@@ -5,14 +5,17 @@ import {
   type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import type {
+  ConfigCascade,
+  ConfigCascadeLevel,
   ConfigKeyDefinition,
   ConfigResolver,
+  ConfigStoredRowWithSource,
   ConfigValueSource,
   ConfigValueWithSource,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { assertUnreachable, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
-import { and, eq, isNull, or } from "drizzle-orm";
+import { and, eq, inArray, isNull, or } from "drizzle-orm";
 import { configValuesTable } from "./table";
 
 type ConfigRow = {
@@ -66,6 +69,148 @@ export type ConfigResolverOptions = {
   appOverrides?: AppConfigOverrides;
 };
 
+// Shared cascade-builder. Single-key path passes a `findRow`-bound row
+// fetcher (one SQL per lookup); batch path passes a closure over
+// pre-loaded rows. The builder itself is unaware of which.
+async function buildCascade(
+  qualifiedKey: string,
+  keyDef: ConfigKeyDefinition,
+  tenantId: string,
+  userId: string,
+  db: DbConnection | TenantDb,
+  fetchRow: (
+    tenantId: string,
+    userId: string | null,
+  ) => Promise<ConfigRow | null> | ConfigRow | null,
+  appOverrides: AppConfigOverrides | undefined,
+  encryption: EncryptionProvider | undefined,
+): Promise<ConfigCascade> {
+  type Lookup = {
+    tenantId: string;
+    userId: string | null;
+    source: ConfigValueSource;
+    label: string;
+  };
+  const lookups: Lookup[] = [];
+
+  switch (keyDef.scope) {
+    case "user":
+      lookups.push({ tenantId, userId, source: "user-row", label: "User" });
+      lookups.push({ tenantId, userId: null, source: "tenant-row", label: "Tenant" });
+      break;
+    case "tenant":
+      lookups.push({ tenantId, userId: null, source: "tenant-row", label: "Tenant" });
+      lookups.push({
+        tenantId: SYSTEM_TENANT_ID,
+        userId: null,
+        source: "system-row",
+        label: "System",
+      });
+      break;
+    case "system":
+      lookups.push({
+        tenantId: SYSTEM_TENANT_ID,
+        userId: null,
+        source: "system-row",
+        label: "System",
+      });
+      break;
+    default:
+      assertUnreachable(keyDef.scope, "config scope");
+  }
+
+  const levels: ConfigCascadeLevel[] = [];
+  let activeIndex = -1;
+
+  for (const lookup of lookups) {
+    const row = await fetchRow(lookup.tenantId, lookup.userId);
+    if (row?.value !== null && row?.value !== undefined) {
+      let raw = row.value;
+      if (keyDef.encrypted && encryption) {
+        raw = encryption.decrypt(raw);
+      }
+      if (activeIndex === -1) activeIndex = levels.length;
+      levels.push({
+        label: lookup.label,
+        value: deserializeValue(raw, keyDef.type),
+        source: lookup.source,
+        isActive: false,
+        hasValue: true,
+      });
+    } else {
+      levels.push({
+        label: lookup.label,
+        value: undefined,
+        source: lookup.source,
+        isActive: false,
+        hasValue: false,
+      });
+    }
+  }
+
+  const overrideValue = appOverrides?.get(qualifiedKey);
+  const hasOverride = overrideValue !== undefined;
+  if (activeIndex === -1 && hasOverride) activeIndex = levels.length;
+  levels.push({
+    label: "App-Override",
+    value: overrideValue,
+    source: "app-override",
+    isActive: false,
+    hasValue: hasOverride,
+  });
+
+  if (keyDef.computed) {
+    const value = await keyDef.computed({ tenantId, userId, db });
+    if (activeIndex === -1) activeIndex = levels.length;
+    levels.push({
+      label: "Computed",
+      value,
+      source: "computed",
+      isActive: false,
+      hasValue: true,
+    });
+  } else {
+    levels.push({
+      label: "Computed",
+      value: undefined,
+      source: "computed",
+      isActive: false,
+      hasValue: false,
+    });
+  }
+
+  if (keyDef.default !== undefined) {
+    if (activeIndex === -1) activeIndex = levels.length;
+    levels.push({
+      label: "Default",
+      value: keyDef.default,
+      source: "default",
+      isActive: false,
+      hasValue: true,
+    });
+  } else {
+    if (activeIndex === -1) activeIndex = levels.length;
+    levels.push({
+      label: "Default",
+      value: undefined,
+      source: "missing",
+      isActive: false,
+      hasValue: false,
+    });
+  }
+
+  const active = activeIndex >= 0 ? levels[activeIndex] : undefined;
+  if (active !== undefined) {
+    levels[activeIndex] = { ...active, isActive: true };
+  }
+
+  return {
+    value: active?.value,
+    source: active?.source ?? "missing",
+    levels,
+  };
+}
+
 export function createConfigResolver(options: ConfigResolverOptions = {}): ConfigResolver {
   const { encryption, appOverrides } = options;
   async function findRow(
@@ -193,6 +338,133 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
 
       return result;
     },
+
+    async getAllWithSource(tenantId, userId, db) {
+      // Load ALL potentially relevant rows (user + tenant + system)
+      const rows = await db
+        .select()
+        .from(configValuesTable)
+        .where(
+          or(
+            and(eq(configValuesTable.tenantId, SYSTEM_TENANT_ID), isNull(configValuesTable.userId)),
+            and(eq(configValuesTable.tenantId, tenantId), isNull(configValuesTable.userId)),
+            and(eq(configValuesTable.tenantId, tenantId), eq(configValuesTable.userId, userId)),
+          ),
+        );
+
+      const result = new Map<string, ConfigStoredRowWithSource>();
+
+      // Group rows by key so we can determine the winner and its source
+      const groups = new Map<string, ConfigRow[]>();
+      for (const row of rows) {
+        const r = row as ConfigRow; // @cast-boundary db-row
+        const g = groups.get(r.key) ?? [];
+        g.push(r);
+        groups.set(r.key, g);
+      }
+
+      for (const [key, keyRows] of groups) {
+        const specificityOf = (candidate: ConfigRow) =>
+          (candidate.userId !== null ? 2 : 0) + (candidate.tenantId !== SYSTEM_TENANT_ID ? 1 : 0);
+
+        const first = keyRows[0];
+        if (!first) continue;
+        let winner: ConfigRow = first;
+        for (const r of keyRows) {
+          if (specificityOf(r) > specificityOf(winner)) {
+            winner = r;
+          }
+        }
+
+        let source: ConfigValueSource;
+        if (winner.userId !== null) {
+          source = "user-row";
+        } else if (winner.tenantId !== SYSTEM_TENANT_ID) {
+          source = "tenant-row";
+        } else {
+          source = "system-row";
+        }
+
+        result.set(key, { ...winner, source });
+      }
+
+      return result;
+    },
+
+    async getCascade(qualifiedKey, keyDef, tenantId, userId, db): Promise<ConfigCascade> {
+      // Single-key path uses findRow per cascade step. The batch path
+      // bulk-loads all rows up-front; both build identical levels arrays.
+      return buildCascade(
+        qualifiedKey,
+        keyDef,
+        tenantId,
+        userId,
+        db,
+        (tid, uid) => findRow(qualifiedKey, tid, uid, db),
+        appOverrides,
+        encryption,
+      );
+    },
+
+    async getCascadeBatch(
+      keys,
+      keyDefs,
+      tenantId,
+      userId,
+      db,
+    ): Promise<ReadonlyMap<string, ConfigCascade>> {
+      if (keys.length === 0) return new Map();
+
+      // One SQL query for all keys + every scope (user-row,
+      // tenant-row, system-row). The cascade-builder then matches
+      // per-key from this preloaded set instead of querying again.
+      const rows = await db
+        .select()
+        .from(configValuesTable)
+        .where(
+          and(
+            inArray(configValuesTable.key, [...keys]),
+            or(
+              and(
+                eq(configValuesTable.tenantId, SYSTEM_TENANT_ID),
+                isNull(configValuesTable.userId),
+              ),
+              and(eq(configValuesTable.tenantId, tenantId), isNull(configValuesTable.userId)),
+              and(eq(configValuesTable.tenantId, tenantId), eq(configValuesTable.userId, userId)),
+            ),
+          ),
+        );
+
+      const grouped = new Map<string, ConfigRow[]>();
+      for (const row of rows) {
+        const r = row as ConfigRow; // @cast-boundary db-row
+        const g = grouped.get(r.key) ?? [];
+        g.push(r);
+        grouped.set(r.key, g);
+      }
+
+      const result = new Map<string, ConfigCascade>();
+      for (const key of keys) {
+        const keyDef = keyDefs.get(key);
+        if (!keyDef) continue;
+
+        const keyRows = grouped.get(key) ?? [];
+        const cascade = await buildCascade(
+          key,
+          keyDef,
+          tenantId,
+          userId,
+          db,
+          (tid, uid) =>
+            keyRows.find((r) => r.tenantId === tid && (r.userId ?? null) === uid) ?? null,
+          appOverrides,
+          encryption,
+        );
+        result.set(key, cascade);
+      }
+
+      return result;
+    },
   };
 }
 

package/src/template-resolver/api.ts

@@ -129,20 +129,34 @@ async function fetchTemplate(
 }
 
 function toPublic(row: TemplateResourceRow): TemplateResource {
+  // @cast-boundary db-row — Drizzle-Schema typisiert kind/contentFormat/
+  // scope/status als generic text. CHECK-Constraints in der DB schränken
+  // sie auf die Union-Types ein; Cast assertet das Schema-Wissen.
+  // linkedResources ist ein text-column mit JSON-payload (string→string map).
+  const kind = row.kind as RenderKind;
+  // @cast-boundary db-row — siehe kind.
+  const contentFormat = row.contentFormat as ContentFormat;
+  // @cast-boundary db-row — siehe kind.
+  const scope = row.scope as "system" | "tenant";
+  // @cast-boundary db-row — siehe kind.
+  const status = row.status as "draft" | "active" | "archived";
+  // @cast-boundary db-row — parseJson returnt Record<string, unknown>;
+  // linkedResources-Spalte enthält per Schema {key: signedUrl}-Map.
+  const linkedResources = parseJson(row.linkedResources) as Record<string, string>;
   return {
     id: String(row.id),
     version: row.version,
     tenantId: row.tenantId,
     slug: row.slug,
-    kind: row.kind as RenderKind,
+    kind,
     locale: row.locale,
     content: row.content ?? "",
-    contentFormat: row.contentFormat as ContentFormat,
+    contentFormat,
     variableSchema: parseJson(row.variableSchema),
-    linkedResources: parseJson(row.linkedResources) as Record<string, string>,
-    scope: row.scope as "system" | "tenant",
+    linkedResources,
+    scope,
     parentTemplateId: row.parentTemplateId,
-    status: row.status as "draft" | "active" | "archived",
+    status,
     updatedAt: row.updatedAt,
   };
 }
@@ -151,6 +165,8 @@ function parseJson(raw: string | null): Record<string, unknown> {
   if (!raw) return {};
   try {
     const parsed = JSON.parse(raw);
+    // @cast-boundary engine-payload — JSON.parse returnt unknown, typeof-Guard
+    // grenzt auf object ein; Record<string, unknown> ist der minimale common-shape.
     return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : {};
   } catch {
     return {};

package/src/template-resolver/handlers/list.query.ts

@@ -48,6 +48,8 @@ export const listQuery = defineQueryHandler({
 
     const whereExpr = conditions.length > 0 ? and(...conditions) : undefined;
 
+    // @cast-boundary db-row — db.select returnt unknown[]; Row-Shape ist
+    // durch templateResourcesTable + buildBaseColumns garantiert.
     const rows = (await ctx.db
       .select()
       .from(templateResourcesTable)

package/src/template-resolver/handlers/upsert-system.write.ts

@@ -19,6 +19,8 @@ export const upsertSystemWrite = defineWriteHandler({
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
     const db = ctx.db;
+    // @cast-boundary engine-payload — SYSTEM_TENANT_ID ist UUID-Literal,
+    // assert auf TenantId-Branded-Type (parseTenantId-Equivalent).
     const tenantId = SYSTEM_TENANT_ID as TenantId;
     // executor-user muss SYSTEM_TENANT als tenantId haben, sonst sucht
     // event-store stream unter user.tenantId statt SYSTEM_TENANT → conflict.
@@ -63,10 +65,14 @@ export const upsertSystemWrite = defineWriteHandler({
 
     const result = await executor.create({ ...fields, tenantId }, executorUser, db);
     if (!result.isSuccess) return result;
+    // @cast-boundary db-row — executor.create returnt Record-row aus
+    // INSERT RETURNING; shape { id } ist garantiert weil PK in der
+    // Returning-Klausel ist.
+    const createdRow = result.data as { id: string | number };
     return {
       isSuccess: true as const,
       data: {
-        id: String((result.data as { id: string | number }).id),
+        id: String(createdRow.id),
         slug: event.payload.slug,
         isNew: true,
       },

package/src/template-resolver/handlers/upsert-tenant.write.ts

@@ -46,6 +46,9 @@ export const upsertTenantWrite = defineWriteHandler({
         }),
       );
     }
+    // @cast-boundary engine-payload — override aus Zod-parsed string,
+    // event.user.tenantId schon TenantId-branded; union als TenantId casten
+    // ist legit (override ist UUID-Format-validiert in schema).
     const tenantId = (override ?? event.user.tenantId) as TenantId;
     const executorUser = override !== undefined ? { ...event.user, tenantId } : event.user;
 
@@ -86,10 +89,14 @@ export const upsertTenantWrite = defineWriteHandler({
 
     const result = await executor.create({ ...fields, tenantId }, executorUser, db);
     if (!result.isSuccess) return result;
+    // @cast-boundary db-row — executor.create returnt Record-row aus
+    // INSERT RETURNING; shape { id } ist garantiert weil PK in der
+    // Returning-Klausel ist.
+    const createdRow = result.data as { id: string | number };
     return {
       isSuccess: true as const,
       data: {
-        id: String((result.data as { id: string | number }).id),
+        id: String(createdRow.id),
         slug: event.payload.slug,
         isNew: true,
       },