@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/text-content/constants.ts

@@ -0,0 +1,19 @@
+// Feature name
+export const TEXT_CONTENT_FEATURE = "text-content" as const;
+
+// Qualified write handler names (QN format: scope:type:name)
+export const TextContentHandlers = {
+  set: "text-content:write:set",
+} as const;
+
+// Qualified query handler names (QN format: scope:type:name)
+export const TextContentQueries = {
+  bySlug: "text-content:query:by-slug",
+} as const;
+
+// Error codes
+export const TextContentErrors = {
+  notFound: "text_block_not_found",
+  invalidSlug: "invalid_slug",
+  invalidLang: "invalid_lang",
+} as const;

package/src/text-content/feature.ts

@@ -0,0 +1,29 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { bySlugQuery } from "./handlers/by-slug.query";
+import { setWrite } from "./handlers/set.write";
+import { textBlockEntity } from "./table";
+
+// text-content — generischer Container für statische Texte (Impressum,
+// Datenschutz, FAQ, About, ToS, Marketing-Snippets). Pro
+// (tenantId, slug, lang) genau ein Block. Inhalt ist Markdown — die
+// Konvertierung zu HTML übernehmen Consumer-Features wie legal-pages
+// (das opt-in obendrauf-Feature für Compliance-Pages).
+//
+// Opt-in: wer keine statischen Texte braucht (interne Tools), aktiviert
+// das Feature gar nicht. Wer es aktiviert, hat sofort CRUD + by-slug-
+// query — Routes/Render kommen pro Use-Case (legal-pages, etc.).
+export function createTextContentFeature(): FeatureDefinition {
+  return defineFeature("text-content", (r) => {
+    r.entity("text-block", textBlockEntity);
+
+    const handlers = {
+      set: r.writeHandler(setWrite),
+    };
+
+    const queries = {
+      bySlug: r.queryHandler(bySlugQuery),
+    };
+
+    return { handlers, queries };
+  });
+}

package/src/text-content/handlers/by-slug.query.ts

@@ -0,0 +1,55 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { type TextBlockRow, textBlocksTable } from "../table";
+
+// Public-Read by (tenantId, slug, lang). Anonymous: muss `anonymous`
+// in roles enthalten — openToAll alleine ist auth-only (Regression-
+// Guard). Tenant-Scope kommt default aus query.user.tenantId (anonymous-
+// context setzt SYSTEM_TENANT_ID oder Host-resolved-tenant je nach App-
+// Setup). Optional `tenantIdOverride` (SystemAdmin-only) erlaubt cross-
+// tenant Read — symmetrisch zum set-handler. Use-case: Edit-UI lädt den
+// SYSTEM_TENANT-Block für SystemAdmin der nicht direkt drauf member ist.
+export const bySlugQuery = defineQueryHandler({
+  name: "by-slug",
+  schema: z.object({
+    slug: z.string().min(1).max(64),
+    lang: z.string().min(2).max(8),
+    /** Optional cross-tenant read — nur für SystemAdmin. Siehe
+     *  set.write.ts für die symmetrische write-side. */
+    tenantIdOverride: z.string().min(1).optional(),
+  }),
+  // Public-Read: muss explizit `anonymous` enthalten damit no-JWT-
+  // Visitors auf Marketing-/Legal-Pages den Text sehen. openToAll
+  // alleine ist auth-only (Regression-Guard) — siehe
+  // docs/plans/datenschutz/legal-artifacts.md.
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const override = query.payload.tenantIdOverride;
+    if (override !== undefined && !query.user.roles.includes("SystemAdmin")) {
+      throw new AccessDeniedError({
+        i18nKey: "textContent.errors.tenantOverrideRequiresSystemAdmin",
+        details: { reason: "tenant_override_requires_system_admin" },
+      });
+    }
+    const tenantId = override ?? query.user.tenantId;
+    const row = await fetchOne<TextBlockRow>(
+      ctx.db,
+      textBlocksTable,
+      eq(textBlocksTable["tenantId"], tenantId),
+      eq(textBlocksTable["slug"], query.payload.slug),
+      eq(textBlocksTable["lang"], query.payload.lang),
+    );
+
+    if (!row) return null;
+    return {
+      slug: row.slug,
+      lang: row.lang,
+      title: row.title,
+      body: row.body,
+      updatedAt: row.updatedAt,
+    };
+  },
+});

package/src/text-content/handlers/set.write.ts

@@ -0,0 +1,118 @@
+import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { type TextBlockRow, textBlockEntity, textBlocksTable } from "../table";
+
+const slugSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9][a-z0-9-]*$/, "slug must be kebab-case (lowercase, digits, dashes)");
+
+const langSchema = z
+  .string()
+  .min(2)
+  .max(8)
+  .regex(/^[a-z]{2}(-[a-z]{2})?$/i, "lang must be ISO 639-1 (e.g. de, en, en-us)");
+
+const executor = createEventStoreExecutor(textBlocksTable, textBlockEntity, {
+  entityName: "text-block",
+});
+
+// Upsert handler — eine Operation pro (tenantId, slug, lang). Bei
+// existierender Row → update, sonst → create. Tenant-Scope kommt
+// default aus event.user. Tenant-Admins setzen Texte für ihren
+// eigenen Tenant; Plattform-Sysadmins können via optional
+// `tenantIdOverride` für einen anderen Tenant schreiben (typisch:
+// SYSTEM_TENANT_ID für legal-pages-content den die ganze Plattform
+// teilt). Override ist SystemAdmin-only — TenantAdmin's Override-
+// Versuch → 403.
+export const setWrite = defineWriteHandler({
+  name: "set",
+  schema: z.object({
+    slug: slugSchema,
+    lang: langSchema,
+    title: z.string().min(1).max(200),
+    body: z.string().max(100_000).nullable(),
+    /** Optional cross-tenant write — nur für SystemAdmin. Typischer
+     *  use-case: legal-pages-Edit-UI lässt SystemAdmin auf
+     *  SYSTEM_TENANT_ID schreiben (sonst landet der text auf seinem
+     *  eigenen platform-tenant und legal-pages-routes lesen ihn
+     *  nicht). TenantAdmin's Versuch → ForbiddenError. */
+    tenantIdOverride: z.string().min(1).optional(),
+  }),
+  // SystemAdmin ist eine GLOBALE Rolle (users.roles), TenantAdmin pro
+  // tenant-membership. SystemAdmin braucht beide Pfade explizit weil
+  // er nicht implicit TenantAdmin auf jedem Tenant ist (siehe
+  // project_global_roles_sysadmin memory). Ohne SystemAdmin könnte
+  // niemand SYSTEM_TENANT-Texte setzen — nur via Test-Helper.
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const db = ctx.db;
+    const override = event.payload.tenantIdOverride;
+    if (override !== undefined && !event.user.roles.includes("SystemAdmin")) {
+      return writeFailure(
+        new AccessDeniedError({
+          i18nKey: "textContent.errors.tenantOverrideRequiresSystemAdmin",
+          details: { reason: "tenant_override_requires_system_admin" },
+        }),
+      );
+    }
+    const tenantId = override ?? event.user.tenantId;
+    // Bei tenantIdOverride muss auch der user-context auf den ziel-tenant
+    // umgestellt werden, sonst läuft der event-store-Lookup
+    // (getStreamVersion) gegen user.tenantId statt tenantId — und findet
+    // den stream nicht → version_conflict obwohl die projection-row da ist.
+    // Symmetrisch zu seedTextBlock, das TestUsers.systemAdmin (tenantId =
+    // SYSTEM_TENANT) als by verwendet.
+    const executorUser =
+      override !== undefined ? { ...event.user, tenantId: override as TenantId } : event.user;
+
+    const existing = await fetchOne<TextBlockRow>(
+      db,
+      textBlocksTable,
+      eq(textBlocksTable["tenantId"], tenantId),
+      eq(textBlocksTable["slug"], event.payload.slug),
+      eq(textBlocksTable["lang"], event.payload.lang),
+    );
+
+    if (existing) {
+      const result = await executor.update(
+        {
+          id: existing.id,
+          version: existing.version,
+          changes: {
+            title: event.payload.title,
+            body: event.payload.body,
+          },
+        },
+        executorUser,
+        db,
+      );
+      if (!result.isSuccess) return result;
+      return {
+        isSuccess: true as const,
+        data: { slug: event.payload.slug, lang: event.payload.lang, isNew: false },
+      };
+    }
+
+    const result = await executor.create(
+      {
+        slug: event.payload.slug,
+        lang: event.payload.lang,
+        title: event.payload.title,
+        body: event.payload.body,
+        tenantId,
+      },
+      executorUser,
+      db,
+    );
+    if (!result.isSuccess) return result;
+    return {
+      isSuccess: true as const,
+      data: { slug: event.payload.slug, lang: event.payload.lang, isNew: true },
+    };
+  },
+});

package/src/text-content/index.ts

@@ -0,0 +1,14 @@
+export {
+  createTextContentApi,
+  requireTextContent,
+  type TextBlock,
+  type TextContentApi,
+} from "./api";
+export {
+  TEXT_CONTENT_FEATURE,
+  TextContentErrors,
+  TextContentHandlers,
+  TextContentQueries,
+} from "./constants";
+export { createTextContentFeature } from "./feature";
+export { type TextBlockRow, textBlockEntity, textBlocksTable } from "./table";

package/src/text-content/seeding.ts

@@ -0,0 +1,91 @@
+// Test-Helper für text-content. Legt einen TextBlock direkt über den
+// Event-Store-Executor an — gleicher Pfad wie der echte set-Handler,
+// aber ohne Access-Check. Idempotent: zweiter Call mit gleichem
+// (tenantId, slug, lang) updated den existing Block.
+
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  fetchOne,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { eq } from "drizzle-orm";
+import { type TextBlockRow, textBlockEntity, textBlocksTable } from "./table";
+
+const executor = createEventStoreExecutor(textBlocksTable, textBlockEntity, {
+  entityName: "text-block",
+});
+
+export type SeedTextBlockOptions = {
+  readonly tenantId: TenantId;
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body?: string | null;
+  readonly by?: SessionUser;
+};
+
+export async function seedTextBlock(
+  db: DbConnection,
+  opts: SeedTextBlockOptions,
+): Promise<{ id: string | number }> {
+  // Default-user muss user.tenantId === opts.tenantId haben, sonst
+  // landet der event-store-stream im user.tenantId-bucket aber die
+  // projection-row im opts.tenantId-bucket. Spätere echte writes via
+  // set-handler (mit korrektem tenant-context) finden den stream
+  // nicht → version_conflict. TestUsers.systemAdmin ist hardcoded
+  // testTenantId(1), nicht opts.tenantId — explizit überschreiben.
+  const by = opts.by ?? { ...TestUsers.systemAdmin, tenantId: opts.tenantId };
+  // executor.create erwartet TenantDb — wrapping nötig damit die runtime-
+  // checks (tenant-scope-validation) greifen.
+  const tdb = createTenantDb(db, opts.tenantId, "system");
+
+  const existing = await fetchOne<TextBlockRow>(
+    db,
+    textBlocksTable,
+    eq(textBlocksTable["tenantId"], opts.tenantId),
+    eq(textBlocksTable["slug"], opts.slug),
+    eq(textBlocksTable["lang"], opts.lang),
+  );
+
+  if (existing) {
+    const result = await executor.update(
+      {
+        id: existing.id,
+        version: existing.version,
+        changes: { title: opts.title, body: opts.body ?? null },
+      },
+      by,
+      tdb,
+    );
+    if (!result.isSuccess) {
+      throw new Error(`seedTextBlock update failed: ${JSON.stringify(result)}`);
+    }
+    return { id: existing.id };
+  }
+
+  const result = await executor.create(
+    {
+      slug: opts.slug,
+      lang: opts.lang,
+      title: opts.title,
+      body: opts.body ?? null,
+      tenantId: opts.tenantId,
+    },
+    by,
+    tdb,
+  );
+  if (!result.isSuccess) {
+    throw new Error(`seedTextBlock create failed: ${JSON.stringify(result)}`);
+  }
+  // @cast-boundary db-row executor.create result.data ist Drizzle-row
+  // (Record<string, unknown>), projected nach INSERT/RETURNING auf
+  // TextBlockRow. Runtime-narrowing in der nächsten Zeile.
+  const data = result.data as Partial<TextBlockRow>;
+  if (data.id === undefined) {
+    throw new Error("seedTextBlock: executor.create did not return an id");
+  }
+  return { id: data.id };
+}

package/src/text-content/table.ts

@@ -0,0 +1,45 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+// TextBlock — generischer Container für statische Texte (legal pages,
+// FAQ, About, ToS, Marketing-Snippets). Pro (tenantId, slug, lang) genau
+// eine Row. SYSTEM_TENANT_ID für app-weite Texte (Impressum etc.), sonst
+// Tenant-eigene Texte.
+//
+// Inhaltsformat ist Markdown (App-Renderer entscheidet Markdown→HTML).
+// Body bleibt nullable damit ein leerer Block existieren kann (z.B.
+// während Tenant-Onboarding bevor der Admin den finalen Text schreibt).
+export const textBlockEntity = createEntity({
+  table: "read_text_blocks",
+  fields: {
+    slug: createTextField({ required: true }),
+    lang: createTextField({ required: true }),
+    title: createTextField({ required: true }),
+    body: createTextField({}),
+  },
+  indexes: [
+    { unique: true, columns: ["tenantId", "slug", "lang"], name: "read_text_blocks_unique" },
+  ],
+});
+
+export const textBlocksTable = buildDrizzleTable("text-block", textBlockEntity);
+
+// Concrete Row-Type — single-source dafür dass die unknown-Werte die
+// Drizzle aus `Record<string, unknown>` liefert genau einmal benannt
+// werden (statt 6× `row["x"] as Y` Casts in Handlern + Seeding).
+// Kommt aus `entity.fields` + Standard-Spalten (id, version, tenantId,
+// createdAt, updatedAt, createdBy, updatedBy) die buildBaseColumns
+// erzwingt.
+export type TextBlockRow = {
+  readonly id: string | number;
+  readonly version: number;
+  readonly tenantId: string;
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body: string | null;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly createdBy: string;
+  readonly updatedBy: string;
+};

package/src/tier-engine/__tests__/compose-app.test.ts

@@ -0,0 +1,182 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { describe, expect, test } from "vitest";
+import { type AddOnMap, composeApp, type TierMap } from "../compose-app";
+
+// --- App-spezifischer Cap-Shape (typed, kein Record<string, unknown>) ---
+
+type AppCaps = {
+  readonly apps: number;
+  readonly mailsPerMonth: number;
+};
+
+// --- Test fixtures ---
+
+const baseFeature = defineFeature("auth", () => {});
+const tenantF = defineFeature("tenant", () => {});
+const designerF = defineFeature("designer", () => {});
+const aiPatchF = defineFeature("ai-patch", () => {});
+const aiConvF = defineFeature("ai-conversation", () => {});
+const byokEncF = defineFeature("byok-encryption", () => {});
+const dedicatedF = defineFeature("dedicated-stack", () => {});
+
+const featureRegistry: Record<string, FeatureDefinition> = {
+  designer: designerF,
+  "ai-patch": aiPatchF,
+  "ai-conversation": aiConvF,
+  "byok-encryption": byokEncF,
+  "dedicated-stack": dedicatedF,
+};
+
+const tierMap: TierMap<AppCaps> = {
+  free: { features: [], caps: { apps: 1, mailsPerMonth: 1000 } },
+  pro: { features: ["designer", "ai-patch"], caps: { apps: 5, mailsPerMonth: 10_000 } },
+  business: {
+    features: ["designer", "ai-patch", "ai-conversation"],
+    caps: { apps: 20, mailsPerMonth: 50_000 },
+  },
+};
+
+const addOnMap: AddOnMap<AppCaps> = {
+  "byok-encryption": { features: ["byok-encryption"] },
+  "dedicated-stack": {
+    features: ["dedicated-stack"],
+    capOverrides: { mailsPerMonth: 100_000 },
+  },
+};
+
+// --- Tests ---
+
+describe("composeApp", () => {
+  test("Free tier mounts only base features", () => {
+    const result = composeApp<AppCaps>({
+      base: [baseFeature, tenantF],
+      featureRegistry,
+      tierMap,
+      addOnMap,
+      tier: "free",
+      addOns: [],
+    });
+
+    expect(result.features.map((f) => f.name)).toEqual(["auth", "tenant"]);
+    // Typed caps — `result.caps.apps` is `number`, not `unknown`.
+    expect(result.caps.apps).toBe(1);
+    expect(result.caps.mailsPerMonth).toBe(1000);
+  });
+
+  test("Pro tier adds Designer + ai-patch", () => {
+    const result = composeApp<AppCaps>({
+      base: [baseFeature, tenantF],
+      featureRegistry,
+      tierMap,
+      addOnMap,
+      tier: "pro",
+      addOns: [],
+    });
+
+    expect(result.features.map((f) => f.name)).toEqual(["auth", "tenant", "designer", "ai-patch"]);
+    expect(result.caps).toEqual({ apps: 5, mailsPerMonth: 10_000 });
+  });
+
+  test("Add-On adds its features on top of tier", () => {
+    const result = composeApp<AppCaps>({
+      base: [baseFeature],
+      featureRegistry,
+      tierMap,
+      addOnMap,
+      tier: "pro",
+      addOns: ["byok-encryption"],
+    });
+
+    expect(result.features.map((f) => f.name)).toEqual([
+      "auth",
+      "designer",
+      "ai-patch",
+      "byok-encryption",
+    ]);
+  });
+
+  test("Add-On capOverrides win over tier caps", () => {
+    const result = composeApp<AppCaps>({
+      base: [baseFeature],
+      featureRegistry,
+      tierMap,
+      addOnMap,
+      tier: "pro",
+      addOns: ["dedicated-stack"],
+    });
+
+    expect(result.caps).toEqual({
+      apps: 5, // from pro
+      mailsPerMonth: 100_000, // overridden by dedicated-stack
+    });
+  });
+
+  test("dedupe — feature listed in tier and add-on mounts only once", () => {
+    // Set up an add-on that re-lists ai-patch (which Pro already has).
+    const overlapAddOnMap: AddOnMap<AppCaps> = {
+      ...addOnMap,
+      "ai-power-pack": { features: ["ai-patch", "ai-conversation"] },
+    };
+
+    const result = composeApp<AppCaps>({
+      base: [],
+      featureRegistry,
+      tierMap,
+      addOnMap: overlapAddOnMap,
+      tier: "pro",
+      addOns: ["ai-power-pack"],
+    });
+
+    // ai-patch only mounts once, ai-conversation mounts as add-on extension.
+    const names = result.features.map((f) => f.name);
+    expect(names).toEqual(["designer", "ai-patch", "ai-conversation"]);
+    expect(names.filter((n) => n === "ai-patch")).toHaveLength(1);
+  });
+
+  test("unknown tier throws with helpful message", () => {
+    expect(() =>
+      composeApp<AppCaps>({
+        base: [],
+        featureRegistry,
+        tierMap,
+        addOnMap,
+        tier: "platinum",
+        addOns: [],
+      }),
+    ).toThrow(/unknown tier "platinum"/);
+  });
+
+  test("unknown add-on throws with helpful message", () => {
+    expect(() =>
+      composeApp<AppCaps>({
+        base: [],
+        featureRegistry,
+        tierMap,
+        addOnMap,
+        tier: "free",
+        addOns: ["unicorn-mode"],
+      }),
+    ).toThrow(/unknown add-on "unicorn-mode"/);
+  });
+
+  test("tier referencing unknown feature throws", () => {
+    const brokenTierMap: TierMap<AppCaps> = {
+      ...tierMap,
+      "broken-tier": {
+        features: ["does-not-exist"],
+        caps: { apps: 0, mailsPerMonth: 0 },
+      },
+    };
+
+    expect(() =>
+      composeApp<AppCaps>({
+        base: [],
+        featureRegistry,
+        tierMap: brokenTierMap,
+        addOnMap,
+        tier: "broken-tier",
+        addOns: [],
+      }),
+    ).toThrow(/unknown feature "does-not-exist"/);
+  });
+});

package/src/tier-engine/__tests__/drift.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "vitest";
+import { tierAssignmentAggregateId } from "../aggregate-id";
+import { TIER_ENGINE_FEATURE, TierEngineHandlers, TierEngineQueries } from "../constants";
+import { tierEngineFeature } from "../feature";
+
+// Drift-Pin-Tests — diese Werte sind Cross-File-Contracts, ein Wechsel
+// muss bewusst geschehen und die anderen Stellen mitziehen. Wenn diese
+// Tests rot werden: stop, denk nach, sync alle Stellen.
+
+describe("tier-engine drift pins", () => {
+  test("TIER_ENGINE_FEATURE matches the registered feature-name", () => {
+    expect(tierEngineFeature.name).toBe(TIER_ENGINE_FEATURE);
+    expect(tierEngineFeature.name).toBe("tier-engine");
+  });
+
+  test("Handler-QNs follow the scope:type:name convention with feature-prefix", () => {
+    expect(TierEngineHandlers.create).toBe("tier-engine:write:tier-assignment:create");
+    expect(TierEngineHandlers.update).toBe("tier-engine:write:tier-assignment:update");
+    expect(TierEngineQueries.list).toBe("tier-engine:query:tier-assignment:list");
+    expect(TierEngineQueries.getActiveTier).toBe("tier-engine:query:get-active-tier");
+
+    // Every QN must start with the feature-name as scope.
+    for (const qn of [...Object.values(TierEngineHandlers), ...Object.values(TierEngineQueries)]) {
+      expect(qn.startsWith(`${TIER_ENGINE_FEATURE}:`)).toBe(true);
+    }
+  });
+
+  test("tier-assignment aggregate-id namespace is stable across boots", () => {
+    // The namespace UUID is in stone — changing it re-keys every existing
+    // aggregate-stream and breaks event-replay + projection-rebuild +
+    // audit-trail. If this test fails: revert the namespace, do not adjust
+    // the test.
+    const id1 = tierAssignmentAggregateId("00000000-0000-4000-8000-000000000001");
+    const id2 = tierAssignmentAggregateId("00000000-0000-4000-8000-000000000001");
+    const id3 = tierAssignmentAggregateId("00000000-0000-4000-8000-000000000002");
+
+    expect(id1).toBe(id2); // same input → same output (deterministic)
+    expect(id1).not.toBe(id3); // different input → different output
+    // Pin the actual value — drift-detector for the namespace constant.
+    expect(id1).toBe("4d7b6b9b-5257-56f7-b668-5d0b92dbd4dc");
+  });
+});