@cosmicdrift/kumiko-bundled-features 0.2.2 → 0.3.0

package/src/text-content/web/client-plugin.ts

@@ -0,0 +1,113 @@
+// @runtime client
+// Client-Feature-Factory für text-content Visual-Tree. Wird vom App-Code
+// in createKumikoApp({ clientFeatures: [textContentClient()] }) eingehängt
+// und liefert den treeProvider der Text-Blocks aus der by-tenant Query
+// lädt, nach Slug-Prefix gruppiert und als TreeNode[] emitted.
+//
+// **Slug-Gruppierung**: Slugs der Form `<prefix>:<rest>` oder `<prefix>/<rest>`
+// werden unter einem `<prefix>`-Container-Knoten gruppiert. Slugs ohne
+// Trenner landen als Top-Level-Knoten. Beispiele:
+//   - "page:index:hero.title" → folder "page", label "index:hero.title"
+//   - "imprint"               → root-node, label "imprint"
+// V.1.3+ kann mehrstufige Hierarchien einführen wenn realer Bedarf zeigt.
+//
+// **State**: TreeNode.state = "filled" wenn body gesetzt ist, sonst
+// "stub" (hellgrau, Designer-Hinweis dass Slug existiert aber leer ist).
+//
+// **Fetch statt Subscribe**: V.1.1 ist Fetch-once beim Mount. Unsubscribe
+// ist no-op. V.1.3+ kann SSE-driven Re-Emit einbauen wenn text-block-
+// updated-Events propagiert werden.
+
+import type { TreeChildrenSubscribe, TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { TextContentQueries } from "../constants";
+
+type BlockSummary = {
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body: string | null;
+  readonly updatedAt: string;
+};
+
+type ByTenantResponse = {
+  readonly data: { readonly blocks: readonly BlockSummary[] };
+};
+
+// Folder-Name = alles vor dem ersten ":" oder "/", oder undefined wenn
+// der Slug keinen Trenner enthält (dann landet er als Root-Node).
+function getFolderName(slug: string): string | undefined {
+  const sepIdx = slug.search(/[:/]/);
+  if (sepIdx === -1) return undefined;
+  return slug.slice(0, sepIdx);
+}
+
+function groupBlocksBySlugPrefix(blocks: readonly BlockSummary[]): readonly TreeNode[] {
+  const rootNodes: TreeNode[] = [];
+  const folders = new Map<string, TreeNode[]>();
+
+  for (const block of blocks) {
+    const node: TreeNode = {
+      label: block.title || block.slug,
+      target: {
+        featureId: "text-content",
+        action: "edit",
+        args: { slug: block.slug, lang: block.lang },
+      },
+      state: block.body ? "filled" : "stub",
+    };
+
+    const folderName = getFolderName(block.slug);
+    if (folderName === undefined) {
+      rootNodes.push(node);
+    } else {
+      const existing = folders.get(folderName) ?? [];
+      existing.push(node);
+      folders.set(folderName, existing);
+    }
+  }
+
+  for (const [name, children] of folders) {
+    rootNodes.push({
+      label: name,
+      icon: "folder",
+      state: "filled",
+      children,
+    });
+  }
+
+  return rootNodes;
+}
+
+const treeProvider: TreeChildrenSubscribe = (_ctx) => (emit) => {
+  fetch("/api/query", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      type: TextContentQueries.byTenant,
+      payload: {},
+    }),
+  })
+    .then((r) => r.json())
+    .then((data: ByTenantResponse) => {
+      const nodes = groupBlocksBySlugPrefix(data.data.blocks);
+      emit(nodes);
+    })
+    .catch(() => {
+      // V.1.3+ TODO: state="error"-Knoten + Reload-Action statt empty.
+      emit([]);
+    });
+  return () => {};
+};
+
+export function textContentClient(): ClientFeatureDefinition {
+  return {
+    name: "text-content",
+    treeProvider,
+    treeActions: {
+      edit: { args: { slug: "" as string, lang: "" as string } },
+      list: {},
+      create: { args: { folder: "" as string } },
+    },
+  };
+}

package/src/text-content/web/index.ts

@@ -0,0 +1,8 @@
+// @runtime client
+// Public exports für die Browser-Seite des text-content Features.
+// Wird über den Sub-Path-Export `@cosmicdrift/kumiko-bundled-features/text-content/web`
+// konsumiert — die Server-Seite (defineFeature) lebt in
+// `@cosmicdrift/kumiko-bundled-features/text-content` und hat keine
+// React-/DOM-Deps. Trennung bleibt sauber so wie renderer vs renderer-web.
+
+export { textContentClient } from "./client-plugin";

package/src/tier-engine/__tests__/auto-default-tier.integration.ts

@@ -0,0 +1,118 @@
+// auto-default-tier hook regression test — beweist dass beim
+// `tenant:write:create` der postSave-Hook von createTierEngineFeature
+// fired und automatisch ein tier-assignment-row mit `defaultTier`
+// schreibt.
+//
+// **Warum dieser Test existiert (2026-05-10):**
+// Der auto-default-tier-Hook wurde in Sprint 8a Phase 2 hinzugefügt aber
+// nie direkt getestet. Bei Sprint 8c (Studio-Mount mit auto-default-
+// compliance-companion-hook) flog der Bug auf: `ctx.db as DbConnection`
+// war ein Type-Lie — TenantDb exposed select/insert/update/delete, NICHT
+// execute(). Der event-store-append (event-store.ts:102) ruft
+// `db.execute(sql\`SELECT pg_notify(...)\`)` → TypeError. Fix:
+// `ctx.db.raw as DbConnection` (Pattern aus signup-confirm.write.ts:107).
+//
+// Pin-Verträge:
+//   1. tenant:write:create fired postSave-Hook mit isNew=true
+//   2. Hook erstellt tier-assignment-row im NEUEN tenant (nicht im caller-
+//      tenant — Memory `feedback_event_store_tenant_consistency`)
+//   3. Idempotency: tenant-update fired keinen weiteren row
+
+import { composeFeatures } from "@cosmicdrift/kumiko-dev-server/compose-features";
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { configValuesTable } from "../../config";
+import { TenantHandlers, tenantMembershipsTable, tenantTable } from "../../tenant";
+import { userTable } from "../../user";
+import type { TierMap } from "../compose-app";
+import { tierAssignmentEntity } from "../entity";
+import { createTierEngineFeature } from "../feature";
+
+const TEST_TIER_MAP: TierMap<{ readonly maxItems: number }> = {
+  free: { features: [], caps: { maxItems: 1 } },
+};
+
+const tierAssignmentTable = buildDrizzleTable("tier-assignment", tierAssignmentEntity);
+
+const features = composeFeatures(
+  [createTierEngineFeature({ defaultTier: "free", tierMap: TEST_TIER_MAP })],
+  { includeBundled: true },
+);
+
+let stack: TestStack;
+const PLATFORM_TENANT = "00000000-0000-4000-8000-000000000001";
+const sysadmin = createTestUser({
+  id: "platform-sysadmin",
+  tenantId: PLATFORM_TENANT,
+  roles: ["SystemAdmin"],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features });
+  await unsafePushTables(stack.db, {
+    config_values: configValuesTable,
+    users: userTable,
+    tenants: tenantTable,
+    tenant_memberships: tenantMembershipsTable,
+    tier_assignments: tierAssignmentTable,
+  });
+});
+
+afterAll(async () => stack?.cleanup());
+
+describe("auto-default-tier postSave hook on tenant-create", () => {
+  test("sysadmin creates a new tenant → free tier-assignment-row angelegt", async () => {
+    const data = (await stack.http.writeOk<Record<string, unknown>>(
+      TenantHandlers.create,
+      { key: "test-tenant-1", name: "Test Tenant One" },
+      sysadmin,
+    ))!;
+    const newTenantId = data["id"] as string;
+    expect(typeof newTenantId).toBe("string");
+
+    const rows = await stack.db
+      .select()
+      .from(tierAssignmentTable)
+      .where(eq(tierAssignmentTable["tenantId"], newTenantId));
+    expect(rows.length).toBe(1);
+    expect((rows[0] as Record<string, unknown>)["tier"]).toBe("free");
+  });
+
+  test("idempotency: tenant-update fired keinen weiteren tier-assignment-row", async () => {
+    const created = (await stack.http.writeOk<Record<string, unknown>>(
+      TenantHandlers.create,
+      { key: "test-tenant-2", name: "Test Tenant Two" },
+      sysadmin,
+    ))!;
+    const tenantId = created["id"] as string;
+
+    const existing = (await stack.db
+      .select()
+      .from(tenantTable)
+      .where(eq(tenantTable["id"], tenantId))) as Array<{ id: string; version: number }>;
+    const currentVersion = existing[0]!.version;
+
+    await stack.http.writeOk(
+      TenantHandlers.update,
+      {
+        id: tenantId,
+        version: currentVersion,
+        changes: { name: "Test Tenant Two — Renamed" },
+      },
+      sysadmin,
+    );
+
+    const rows = await stack.db
+      .select()
+      .from(tierAssignmentTable)
+      .where(eq(tierAssignmentTable["tenantId"], tenantId));
+    expect(rows.length).toBe(1);
+  });
+});

package/src/tier-engine/feature.ts

@@ -197,7 +197,7 @@ export function createTierEngineFeature<
     // Invalidation: tier-assignment events update the cache.
     r.entityHook("postSave", "tier-assignment", async (result) => {
       // result.data has tenantId + tier (after entity-update merge)
-      const data = result.data as { tenantId?: unknown; tier?: unknown };
+      const data = result.data as { tenantId?: unknown; tier?: unknown }; // @cast-boundary engine-payload
       // skip: defensive type-guard auf payload-shape. Bei korrekt gerenderten
       // entity-events sind beide fields immer strings; ein malformed-payload
       // (custom-handler-bug) würde hier silent zum cache-skip führen statt
@@ -210,7 +210,7 @@ export function createTierEngineFeature<
       );
     });
     r.entityHook("postDelete", "tier-assignment", async (payload) => {
-      const data = payload.data as { tenantId?: unknown };
+      const data = payload.data as { tenantId?: unknown }; // @cast-boundary engine-payload
       // skip: gleiche type-guard semantik wie postSave-hook oben.
       if (typeof data.tenantId !== "string") return;
       cache.delete(data.tenantId as TenantId);
@@ -235,16 +235,16 @@ export function createTierEngineFeature<
         "tenant",
         async (result, ctx) => {
           // result-shape: kumiko-framework's SaveContext mit isNew + data
-          const saveResult = result as { isNew?: unknown; data?: unknown };
+          const saveResult = result as { isNew?: unknown; data?: unknown }; // @cast-boundary engine-payload
           // skip: nur bei tenant-create (initial) — tenant-updates feuern
           // auch postSave aber wir wollen kein neues tier-assignment bei
           // re-keying oder name-update.
           if (saveResult.isNew !== true) return;
-          const data = saveResult.data as { id?: unknown };
+          const data = saveResult.data as { id?: unknown }; // @cast-boundary engine-payload
           // skip: defensive type-guard. Tenant-entity hat id zwingend, aber
           // CrudExecutor's payload-shape ist runtime-unknown.
           if (typeof data.id !== "string") return;
-          const newTenantId = data.id as TenantId;
+          const newTenantId = data.id as TenantId; // @cast-boundary engine-payload
           const aggregateId = tierAssignmentAggregateId(newTenantId);
 
           // skip: defensive — inTransaction phase hat ctx.db immer gesetzt,
@@ -253,12 +253,22 @@ export function createTierEngineFeature<
           if (!ctx.db) return;
 
           // ctx.db ist im inTransaction-phase eine TenantDb (tenant-scoped
-          // proxy auf die echte TX). Für event-store-reads (cross-tenant
-          // stream-lookup via aggregate-id) brauchen wir die rohe TX —
-          // TenantDb wrapped die echte DbConnection, der select-call
-          // funktioniert structural identisch. Cast als DbConnection ist
-          // boundary-cast für event-store-API, kein narrowing-escape.
-          const rawDb = ctx.db as DbConnection;
+          // proxy auf die echte TX). Für event-store-Pfade brauchen wir
+          // die rohe DbConnection — TenantDb exposes nur select/insert/
+          // update/delete, NICHT execute (event-store-append.ts:102 ruft
+          // db.execute(sql`SELECT pg_notify(...)`) → TypeError sonst).
+          // Pattern matched signup-confirm.write.ts:107 (.raw), nicht
+          // `as DbConnection` — das ist Type-Lie der erst beim ersten
+          // .execute()-Call crashed.
+          //
+          // AppContext.db ist union (DbConnection | TenantDb). Im
+          // inTransaction-phase garantiert TenantDb — der dispatcher
+          // wrapped vorher (siehe pipeline/dispatcher.ts createTenantDb-
+          // Aufruf). TypeGuard via `"raw" in ...` ist robuster als
+          // `as TenantDb` gegen future refactor.
+          // skip: defensive — sollte im inTransaction nie greifen.
+          if (!("raw" in ctx.db)) return;
+          const rawDb = ctx.db.raw as DbConnection; // @cast-boundary db-runner
 
           // Idempotency: stream-existence-check vor create. Pattern aus
           // seedTenant.ts. Bei re-replay (rebuild) nicht versionsbumpen.
@@ -266,7 +276,7 @@ export function createTierEngineFeature<
           const [streamRow] = (await rawDb
             .select({ v: maxFn(eventsTable.version) })
             .from(eventsTable)
-            .where(eq(eventsTable.aggregateId, aggregateId))) as StreamRow[];
+            .where(eq(eventsTable.aggregateId, aggregateId))) as StreamRow[]; // @cast-boundary db-row
           // skip: idempotency — aggregate-stream existiert schon (re-replay
           // nach projection-rebuild oder hook-retry). create() würde
           // version_conflict werfen + tenant-create rollback'n. Pattern aus
@@ -326,7 +336,7 @@ export function createTierEngineFeature<
         // Skalierungs-Pfad (lazy-load + LRU) ist Sprint-8b wenn echtes
         // Bedürfnis entsteht.
         type AssignmentRow = { tenantId: string; tier: string };
-        const rows = (await deps.db.select().from(tierAssignmentTable)) as AssignmentRow[];
+        const rows = (await deps.db.select().from(tierAssignmentTable)) as AssignmentRow[]; // @cast-boundary db-row
         for (const row of rows) {
           cache.set(
             row.tenantId as TenantId,

package/src/user/__tests__/user-status.test.ts

@@ -0,0 +1,39 @@
+// Drift-Guard fuer USER_STATUS (S2.D2.5 N1).
+//
+// Plus: USER_STATUS_OPTIONS wird nicht direkt exportiert (private im
+// schema/user.ts), wird aber via createSelectField in der Entity
+// referenziert. Wenn USER_STATUS-Object erweitert wird ohne dass das
+// Tuple synchron mitwaechst, faengt der Test es ab — entity.fields.status
+// liefert die options-Liste.
+
+import { describe, expect, test } from "vitest";
+import { USER_STATUS, userEntity } from "../schema/user";
+
+describe("USER_STATUS — Drift-Guard (S2.D2.5 N1)", () => {
+  test("Snapshot-Vergleich: USER_STATUS-Object und entity.fields.status.options synchron", () => {
+    const objectValues = Object.values(USER_STATUS).sort();
+    // entity.fields.status ist createSelectField — options ist die Tuple
+    const statusField = userEntity.fields["status"] as { options: readonly string[] };
+    const optionValues = [...statusField.options].sort();
+
+    expect(optionValues).toEqual(objectValues);
+  });
+
+  test("USER_STATUS-Snapshot — explizit zu updaten bei Aenderungen", () => {
+    expect(USER_STATUS).toMatchInlineSnapshot(`
+      {
+        "Active": "active",
+        "Deleted": "deleted",
+        "DeletionRequested": "deletionRequested",
+        "Restricted": "restricted",
+      }
+    `);
+  });
+
+  test("USER_STATUS-Werte sind camelCase (Convention fuer status-Strings)", () => {
+    // Erwartung: alle Werte starten mit lowercase und enthalten kein Leerzeichen
+    for (const value of Object.values(USER_STATUS)) {
+      expect(value).toMatch(/^[a-z][a-zA-Z]*$/);
+    }
+  });
+});

package/src/user/handlers/find-for-auth.query.ts

@@ -30,7 +30,7 @@ export const findForAuthQuery = defineQueryHandler({
     const condition =
       query.payload.email !== undefined
         ? eq(userTable["email"], query.payload.email)
-        : eq(userTable["id"], query.payload.id as string);
+        : eq(userTable["id"], query.payload.id as string); // @cast-boundary engine-payload
 
     const [row] = await ctx.db.select().from(userTable).where(condition).limit(1);
     return (row as DbRow) ?? null;

package/src/user/index.ts

@@ -1,4 +1,14 @@
 export { UserCommandSchemas } from "./command-schemas";
 export { USER_FEATURE, UserErrors, UserHandlers, UserQueries } from "./constants";
 export { createUserFeature } from "./feature";
-export { userEntity, userTable } from "./schema/user";
+export type { UserStatus } from "./schema/user";
+export {
+  USER_ANONYMIZED_DISPLAY_NAME,
+  USER_ANONYMIZED_EMAIL_DOMAIN,
+  USER_ANONYMIZED_EMAIL_PREFIX,
+  USER_DELETED_DISPLAY_NAME,
+  USER_DELETED_EMAIL_PREFIX,
+  USER_STATUS,
+  userEntity,
+  userTable,
+} from "./schema/user";

package/src/user/schema/user.ts

@@ -3,9 +3,54 @@ import {
   access,
   createBooleanField,
   createEntity,
+  createSelectField,
   createTextField,
+  createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
+/**
+ * User-Lifecycle-Status (S2.U1). Single source of truth — Auth-Middleware
+ * (S2.U6), Forget-Job (S2.U5) und Restriction-Handler nutzen diese
+ * Constants statt Magic-Strings (Memory feedback_role_naming_drift —
+ * gleiches Pattern wie ROLES.SystemAdmin).
+ */
+export const USER_STATUS = {
+  Active: "active",
+  Restricted: "restricted",
+  DeletionRequested: "deletionRequested",
+  Deleted: "deleted",
+} as const;
+
+export type UserStatus = (typeof USER_STATUS)[keyof typeof USER_STATUS];
+
+/**
+ * Anonymize-Display-Strings fuer userDeleteHook (S2.H1). Constants statt
+ * Magic-Strings damit i18n-Mapping moeglich + drift-fest. Default-DE,
+ * App-Author kann via i18n-System uebersetzen wenn gewuenscht.
+ */
+export const USER_DELETED_DISPLAY_NAME = "[Geloescht]";
+export const USER_ANONYMIZED_DISPLAY_NAME = "[Anonymisiert]";
+
+/**
+ * Email-Pseudonyme nach Forget. `<prefix>-<userId>@anonymized.invalid`
+ * — der userId-Suffix ist als Pseudo-Audit-Marker fuer Operator
+ * (Tracing-fall) erlaubt; user-id selbst ist UUID, kein PII.
+ * `.invalid`-TLD ist RFC2606-reserviert — niemals deliverbare Email.
+ */
+export const USER_DELETED_EMAIL_PREFIX = "deleted";
+export const USER_ANONYMIZED_EMAIL_PREFIX = "anonymized";
+export const USER_ANONYMIZED_EMAIL_DOMAIN = "anonymized.invalid";
+
+// Tuple form fuer createSelectField (erfordert non-empty readonly tuple).
+// Object.values(USER_STATUS) waere string[] — statisches Tuple ist
+// type-sicher.
+const USER_STATUS_OPTIONS = [
+  USER_STATUS.Active,
+  USER_STATUS.Restricted,
+  USER_STATUS.DeletionRequested,
+  USER_STATUS.Deleted,
+] as const;
+
 // User entity — tenant-agnostic. A single user can belong to multiple tenants
 // via tenantMemberships. No tenantId column on this table.
 export const userEntity = createEntity({
@@ -63,6 +108,37 @@ export const userEntity = createEntity({
       default: "[]",
       access: { write: access.privileged },
     }),
+
+    // S2.U1: User-Lifecycle-Status für user-data-rights (Sprint 2).
+    //   - "active":            Normaler State, alle Operationen erlaubt
+    //   - "restricted":        Art. 18 Restriction — Auth-Middleware blockiert
+    //                          Schreib-Endpoints, Read bleibt erlaubt damit
+    //                          User das Banner sieht + lift-restriction klicken kann
+    //   - "deletionRequested": delete-account aufgerufen, gracePeriodEnd
+    //                          gesetzt, User kann via cancel-deletion zurueck
+    //                          auf "active". Auth-Middleware blockiert wie
+    //                          "restricted".
+    //   - "deleted":           Forget executed nach Grace, Row anonymisiert via
+    //                          softDelete. Auth-Middleware blockt Login.
+    //
+    // Schreibrecht privileged: nur die request-deletion / restrict / lift /
+    // execute-forget-Handler (alle SYSTEM-context) duerfen status flippen.
+    status: createSelectField({
+      required: true,
+      default: USER_STATUS.Active,
+      options: USER_STATUS_OPTIONS,
+      access: { write: access.privileged },
+    }),
+
+    // Wann darf der pending-Forget tatsaechlich ausgefuehrt werden?
+    // Cron-Job in user-data-rights checkt taeglich gracePeriodEnd < now()
+    // und triggert dann die EXT_USER_DATA-Hooks. NULL solange kein
+    // Forget pending — wird beim delete-account-Call gesetzt
+    // (= now() + Compliance-Profile.userRights.gracePeriod), beim
+    // cancel-deletion zurueckgesetzt.
+    gracePeriodEnd: createTimestampField({
+      access: { write: access.privileged },
+    }),
   },
 });
 

package/src/user/seeding.ts

@@ -57,7 +57,7 @@ export async function seedUser(db: DbConnection, options: SeedUserOptions): Prom
   const tdb = createTenantDb(db, by.tenantId, "system");
 
   const existing = await fetchOne(db, userTable, eq(userTable["email"], options.email));
-  if (existing) return existing["id"] as string;
+  if (existing) return existing["id"] as string; // @cast-boundary db-row
 
   const result = await userExecutor.create(
     {
@@ -86,7 +86,7 @@ export async function seedUser(db: DbConnection, options: SeedUserOptions): Prom
 // als ehrlicher Throw rauskommt statt downstream als undefined-Bug.
 function extractId(data: unknown, who: string): string {
   if (typeof data === "object" && data !== null && "id" in data) {
-    const id = (data as { id: unknown }).id;
+    const id = (data as { id: unknown }).id; // @cast-boundary engine-bridge
     if (typeof id === "string") return id;
   }
   throw new Error(`${who}: executor.create result has no string id (got ${JSON.stringify(data)})`);