@cosmicdrift/kumiko-bundled-features 0.3.0 → 0.4.1

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

@@ -0,0 +1,105 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineWriteHandler,
+  SYSTEM_TENANT_ID,
+  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 { TemplateResourceRow } from "../table";
+import { templateResourcesTable } from "../table";
+import { executor, upsertPayloadSchema } from "./shared";
+
+// Tenant-Override anlegen/updaten. Liegt unter event.user.tenantId,
+// scope='tenant'. Default-Status='draft' — User publisht explizit
+// via publish-Handler. SystemAdmin kann via tenantIdOverride für
+// einen anderen Tenant schreiben (typisch: Plattform-Admin-UI das
+// Tenant-Templates kuratiert).
+export const upsertTenantWrite = defineWriteHandler({
+  name: "upsert-tenant",
+  schema: upsertPayloadSchema.extend({
+    tenantIdOverride: z.string().min(1).optional(),
+    status: z.enum(["draft", "active"]).default("draft"),
+  }),
+  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: "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
+          details: { reason: "tenant_override_requires_system_admin" },
+        }),
+      );
+    }
+    // upsertTenant erzeugt scope='tenant'. SYSTEM_TENANT_ID-Override würde
+    // scope='tenant' unter SYSTEM_TENANT_ID schreiben → inkonsistenter Zustand
+    // (Resolver-Logik trennt sauber zwischen system+tenant). SystemAdmin muss
+    // upsertSystem für System-Defaults nutzen.
+    if (override === SYSTEM_TENANT_ID) {
+      return writeFailure(
+        new AccessDeniedError({
+          i18nKey: "templateResolver.errors.useUpsertSystemForSystemTenant",
+          details: { reason: "system_tenant_override_not_allowed_use_upsert_system" },
+        }),
+      );
+    }
+    // @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;
+
+    const existing = await fetchOne<TemplateResourceRow>(
+      db,
+      templateResourcesTable,
+      eq(templateResourcesTable["tenantId"], tenantId),
+      eq(templateResourcesTable["slug"], event.payload.slug),
+      eq(templateResourcesTable["kind"], event.payload.kind),
+      eq(templateResourcesTable["locale"], event.payload.locale),
+    );
+
+    const fields = {
+      slug: event.payload.slug,
+      kind: event.payload.kind,
+      locale: event.payload.locale,
+      content: event.payload.content,
+      contentFormat: event.payload.contentFormat,
+      variableSchema: JSON.stringify(event.payload.variableSchema),
+      linkedResources: JSON.stringify(event.payload.linkedResources),
+      scope: "tenant" as const,
+      parentTemplateId: event.payload.parentTemplateId ?? null,
+      status: event.payload.status,
+    };
+
+    if (existing) {
+      const result = await executor.update(
+        { id: existing.id, version: existing.version, changes: fields },
+        executorUser,
+        db,
+      );
+      if (!result.isSuccess) return result;
+      return {
+        isSuccess: true as const,
+        data: { id: String(existing.id), slug: event.payload.slug, isNew: false },
+      };
+    }
+
+    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(createdRow.id),
+        slug: event.payload.slug,
+        isNew: true,
+      },
+    };
+  },
+});

package/src/template-resolver/index.ts

@@ -0,0 +1,28 @@
+export {
+  createTemplateResolverApi,
+  type ResolveRequest,
+  requireTemplateResolver,
+  TemplateNotFoundError,
+  type TemplateResolverApi,
+  type TemplateResource,
+} from "./api";
+export {
+  CONTENT_FORMATS,
+  type ContentFormat,
+  FALLBACK_LOCALE,
+  RENDER_KINDS,
+  type RenderKind,
+  SYSTEM_TENANT_ID,
+  TEMPLATE_SCOPES,
+  TEMPLATE_STATUSES,
+  type TemplateScope,
+  type TemplateStatus,
+} from "./constants";
+export { createTemplateResolverFeature } from "./feature";
+export {
+  TEMPLATE_RESOLVER_FEATURE,
+  TemplateResolverErrors,
+  TemplateResolverHandlers,
+  TemplateResolverQueries,
+} from "./qualified-names";
+export { type TemplateResourceRow, templateResourceEntity, templateResourcesTable } from "./table";

package/src/template-resolver/qualified-names.ts

@@ -0,0 +1,24 @@
+// @runtime client
+// Feature name + qualified handler/query names (QN: scope:type:name).
+export const TEMPLATE_RESOLVER_FEATURE = "template-resolver" as const;
+
+export const TemplateResolverHandlers = {
+  upsertSystem: "template-resolver:write:upsert-system",
+  upsertTenant: "template-resolver:write:upsert-tenant",
+  publish: "template-resolver:write:publish",
+  archive: "template-resolver:write:archive",
+} as const;
+
+export const TemplateResolverQueries = {
+  findById: "template-resolver:query:find-by-id",
+  list: "template-resolver:query:list",
+} as const;
+
+export const TemplateResolverErrors = {
+  notFound: "template_resource_not_found",
+  invalidSlug: "invalid_slug",
+  invalidLocale: "invalid_locale",
+  systemAdminRequired: "system_admin_required",
+  alreadyActive: "template_already_active",
+  alreadyArchived: "template_already_archived",
+} as const;

package/src/template-resolver/table.ts

@@ -0,0 +1,67 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createLongTextField,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { CONTENT_FORMATS, RENDER_KINDS, TEMPLATE_SCOPES, TEMPLATE_STATUSES } from "./constants";
+
+// TemplateResource — strukturierte Template-Definition mit Tenant-
+// Override-Hierarchie, Locale-Fallback und Resource-Linking via
+// file-foundation. Pro (tenantId, slug, kind, locale) genau eine Row;
+// scope/status/version differenzieren Lifecycle.
+//
+// `variableSchema` + `linkedResources` sind JSON-Strings in longText
+// (Pattern aus compliance-profiles — kein dedizierter jsonbField im
+// createEntity-DSL). App-Layer parsed JSON, persistiert wieder als String.
+export const templateResourceEntity = createEntity({
+  table: "read_template_resources",
+  fields: {
+    slug: createTextField({ required: true }),
+    kind: createSelectField({ required: true, options: [...RENDER_KINDS] }),
+    locale: createTextField({ required: true }),
+    content: createLongTextField({}),
+    contentFormat: createSelectField({ required: true, options: [...CONTENT_FORMATS] }),
+    variableSchema: createLongTextField({}),
+    linkedResources: createLongTextField({}),
+    scope: createSelectField({ required: true, options: [...TEMPLATE_SCOPES] }),
+    parentTemplateId: createTextField({}),
+    status: createSelectField({ required: true, options: [...TEMPLATE_STATUSES] }),
+  },
+  indexes: [
+    {
+      unique: true,
+      columns: ["tenantId", "slug", "kind", "locale"],
+      name: "read_template_resources_unique",
+    },
+  ],
+});
+
+export const templateResourcesTable = buildDrizzleTable(
+  "template-resource",
+  templateResourceEntity,
+);
+
+// Concrete Row-Type — single-source dafür dass die unknown-Werte die
+// Drizzle aus `Record<string, unknown>` liefert genau einmal benannt
+// werden (statt 12× `row["x"] as Y` Casts in Handlern + Resolver).
+export type TemplateResourceRow = {
+  readonly id: string | number;
+  readonly version: number;
+  readonly tenantId: string;
+  readonly slug: string;
+  readonly kind: string;
+  readonly locale: string;
+  readonly content: string | null;
+  readonly contentFormat: string;
+  readonly variableSchema: string | null;
+  readonly linkedResources: string | null;
+  readonly scope: string;
+  readonly parentTemplateId: string | null;
+  readonly status: string;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly createdBy: string;
+  readonly updatedBy: string;
+};

package/src/text-content/__tests__/text-content.integration.ts

@@ -412,4 +412,58 @@ describe("text-content :: seedTextBlock", () => {
     });
     expect(a.id).toBe(b.id);
   });
+
+  // Drift-Documentation: seedTextBlock geht direkt durch den Executor
+  // OHNE slugSchema-Validation, set.write läuft DURCH die Validation.
+  // Folge: seedTextBlock akzeptiert Slugs mit ":" oder "/" (legal-pages
+  // Plattform-Seeds nutzen das für "page:index:hero.title" etc.), aber
+  // ein User-Edit derselben Block über set.write würde mit
+  // validation_error fail (regex `^[a-z0-9][a-z0-9-]*$`). Drift ist
+  // **bewusst** in V.1.3 — seedTextBlock ist system-trusted (boot-fixture,
+  // kein User-Input). V.1.4 plant ein echtes `folder`-Field statt
+  // `:`-Separator-im-Slug, dann fällt die Drift weg.
+  //
+  // Dieser Test pinnt den Status quo: Editor-Form via set.write rejected
+  // ":"-Slugs auch wenn seedTextBlock sie angelegt hat. Plus-Test
+  // verhindert dass jemand silent seedTextBlock-Validation hinzufügt
+  // ohne app-side seed-Slugs (z.B. legal-pages-Plattform-Seeds) zu
+  // konvertieren.
+  test("seedTextBlock + set.write drift: `:`-slugs sind seed-only, set.write rejected sie", async () => {
+    // Seed mit `:`-Slug funktioniert (legal-pages-Pattern)
+    const seeded = await seedTextBlock(db, {
+      tenantId: tenantAdmin.tenantId,
+      slug: "page:hero",
+      lang: "de",
+      title: "Seeded",
+      body: "from-seed",
+    });
+    expect(seeded.id).toBeDefined();
+
+    // Set.write auf demselben Slug → validation_error (kebab-only regex)
+    const error = await stack.http.writeErr(
+      TextContentHandlers.set,
+      { slug: "page:hero", lang: "de", title: "User-edit", body: "from-write" },
+      tenantAdmin,
+    );
+    expectErrorIncludes(error, "validation_error");
+  });
+
+  test("seedTextBlock + set.write parity: kebab-only Slugs durchlaufen beide Pfade", async () => {
+    // Inverse-Test: für kebab-only Slugs (`page-hero`) klappen beide
+    // Pfade. App-Builder die Edit-Form-fähige Seeds wollen, müssen
+    // kebab-only verwenden (siehe publicstatus/bin/seed-demo.ts).
+    await seedTextBlock(db, {
+      tenantId: tenantAdmin.tenantId,
+      slug: "page-hero",
+      lang: "de",
+      title: "Seeded",
+      body: "from-seed",
+    });
+    const result = await stack.http.writeOk<{ slug: string; lang: string }>(
+      TextContentHandlers.set,
+      { slug: "page-hero", lang: "de", title: "User-edit", body: "from-write" },
+      tenantAdmin,
+    );
+    expect(result.slug).toBe("page-hero");
+  });
 });

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

@@ -49,6 +49,7 @@ export const bySlugQuery = defineQueryHandler({
       lang: row.lang,
       title: row.title,
       body: row.body,
+      folder: row.folder,
       updatedAt: row.updatedAt,
     };
   },

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

@@ -20,6 +20,7 @@ export type TextBlockSummary = {
   readonly lang: string;
   readonly title: string;
   readonly body: string | null;
+  readonly folder: string | null;
   readonly updatedAt: Date;
 };
 
@@ -49,6 +50,7 @@ export const byTenantQuery = defineQueryHandler({
         lang: row.lang,
         title: row.title,
         body: row.body,
+        folder: row.folder,
         updatedAt: row.updatedAt,
       })),
     };

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

@@ -11,6 +11,17 @@ const slugSchema = z
   .max(64)
   .regex(/^[a-z0-9][a-z0-9-]*$/, "slug must be kebab-case (lowercase, digits, dashes)");
 
+// Folder-Convention V.1.4: gleiches kebab-Pattern wie slug, optional
+// `/`-Separator für nested folders ("legal/imprint", "page/marketing").
+// Multi-level wird vom Visual-Tree-Grouping flat-rendered bis V.1.5
+// rekursive Hierarchie braucht — dann erweitert sich nur der UI-Render,
+// nicht das Schema.
+const folderSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)*$/, "folder must be kebab-case path");
+
 const langSchema = z
   .string()
   .min(2)
@@ -36,6 +47,11 @@ export const setWrite = defineWriteHandler({
     lang: langSchema,
     title: z.string().min(1).max(200),
     body: z.string().max(100_000).nullable(),
+    /** V.1.4: Folder-Pfad für Visual-Tree-Gruppierung. Optional + null
+     *  → root-node (kein Folder). Tree groupt nach diesem Field, slug
+     *  bleibt flach + kebab-validiert. Beispiele: "page", "legal",
+     *  "page/marketing". */
+    folder: folderSchema.nullable().optional(),
     /** 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
@@ -78,6 +94,11 @@ export const setWrite = defineWriteHandler({
       eq(textBlocksTable["lang"], event.payload.lang),
     );
 
+    // V.1.4 folder: optional + null erlaubt (root-node). Optional-Chain
+    // mapped undefined → null damit drizzle nullable-column konsistent
+    // schreibt (sonst SQL-default kicked-in vs. explicit-null Unterschied).
+    const folder = event.payload.folder ?? null;
+
     if (existing) {
       const result = await executor.update(
         {
@@ -86,6 +107,7 @@ export const setWrite = defineWriteHandler({
           changes: {
             title: event.payload.title,
             body: event.payload.body,
+            folder,
           },
         },
         executorUser,
@@ -104,6 +126,7 @@ export const setWrite = defineWriteHandler({
         lang: event.payload.lang,
         title: event.payload.title,
         body: event.payload.body,
+        folder,
         tenantId,
       },
       executorUser,

package/src/text-content/seeding.ts

@@ -24,6 +24,11 @@ export type SeedTextBlockOptions = {
   readonly lang: string;
   readonly title: string;
   readonly body?: string | null;
+  /** V.1.4: Folder-Pfad für Visual-Tree-Gruppierung. Optional + null =
+   *  root-node. Seed-Pfad bypasst slugSchema/folderSchema-Validation
+   *  (system-trusted), aber App-Builder sollten kebab-only nutzen damit
+   *  set.write die geseedete Row später überschreiben kann. */
+  readonly folder?: string | null;
   readonly by?: SessionUser;
 };
 
@@ -50,12 +55,14 @@ export async function seedTextBlock(
     eq(textBlocksTable["lang"], opts.lang),
   );
 
+  const folder = opts.folder ?? null;
+
   if (existing) {
     const result = await executor.update(
       {
         id: existing.id,
         version: existing.version,
-        changes: { title: opts.title, body: opts.body ?? null },
+        changes: { title: opts.title, body: opts.body ?? null, folder },
       },
       by,
       tdb,
@@ -72,6 +79,7 @@ export async function seedTextBlock(
       lang: opts.lang,
       title: opts.title,
       body: opts.body ?? null,
+      folder,
       tenantId: opts.tenantId,
     },
     by,

package/src/text-content/table.ts

@@ -16,6 +16,11 @@ export const textBlockEntity = createEntity({
     lang: createTextField({ required: true }),
     title: createTextField({ required: true }),
     body: createTextField({}),
+    // V.1.4: explicit folder-Hierarchie statt `:`-Encoding im Slug.
+    // Visual-Tree gruppiert nach diesem Field; null/undefined → root.
+    // Pflicht-Constraint im set.write-Schema (kebab-only wie slug,
+    // damit App-Builder konsistente Naming-Conventions haben).
+    folder: createTextField({}),
   },
   indexes: [
     { unique: true, columns: ["tenantId", "slug", "lang"], name: "read_text_blocks_unique" },
@@ -38,6 +43,7 @@ export type TextBlockRow = {
   readonly lang: string;
   readonly title: string;
   readonly body: string | null;
+  readonly folder: string | null;
   readonly createdAt: Date;
   readonly updatedAt: Date;
   readonly createdBy: string;

package/src/text-content/web/__tests__/editor-read-only.test.tsx

@@ -0,0 +1,125 @@
+// @vitest-environment jsdom
+
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, test, vi } from "vitest";
+import { textContentClient } from "../client-plugin";
+
+// Mock-Setup für die drei externen Hooks die TextContentEditor benutzt.
+// vi.mock + vi.fn() erlaubt pro-Test verschiedene Roles + Dispatcher-
+// Antworten. Memory `[Keine Fake-Tests]`: wir testen echtes Rendering,
+// nicht nur die canWrite-Bedingung.
+vi.mock("@cosmicdrift/kumiko-bundled-features/auth-email-password/web", () => ({
+  useShellUser: vi.fn(),
+}));
+
+vi.mock("@cosmicdrift/kumiko-renderer", async () => {
+  const actual = await vi.importActual<typeof import("@cosmicdrift/kumiko-renderer")>(
+    "@cosmicdrift/kumiko-renderer",
+  );
+  return {
+    ...actual,
+    useDispatcher: vi.fn(() => ({
+      write: vi.fn(),
+      query: vi.fn(),
+    })),
+    useQuery: vi.fn(() => ({
+      data: { slug: "imprint", lang: "de", title: "Impressum", body: "Inhalt" },
+      loading: false,
+      error: null,
+      refetch: vi.fn(),
+    })),
+  };
+});
+
+import { useShellUser } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+
+const TARGET = {
+  featureId: "text-content",
+  action: "edit",
+  args: { slug: "imprint", lang: "de" },
+} as const;
+
+function getEditor() {
+  const def = textContentClient();
+  const Editor = def.resolvers?.["text-content:edit"];
+  if (!Editor) throw new Error("Editor not registered");
+  return Editor;
+}
+
+const localeResolver = createStaticLocaleResolver();
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={localeResolver}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("TextContentEditor — role-based write-access", () => {
+  test("TenantAdmin sieht Save-Button + editable inputs", () => {
+    vi.mocked(useShellUser).mockReturnValue({ id: "u1", roles: ["TenantAdmin"] });
+    const Editor = getEditor();
+    render(<Editor target={TARGET} onClose={() => {}} />, { wrapper: Wrapper });
+
+    // Save-Button gerendert (canWrite=true → Button.type=submit)
+    const saveButton = screen.getByRole("button", { name: /speichern/i });
+    expect(saveButton).toBeTruthy();
+    expect(saveButton.hasAttribute("disabled")).toBe(false);
+
+    // Read-only-Banner darf NICHT erscheinen
+    expect(screen.queryByText(/Read-only/)).toBeNull();
+  });
+
+  test("SystemAdmin sieht Save-Button (alternative write-role)", () => {
+    vi.mocked(useShellUser).mockReturnValue({ id: "u1", roles: ["SystemAdmin"] });
+    const Editor = getEditor();
+    render(<Editor target={TARGET} onClose={() => {}} />, { wrapper: Wrapper });
+
+    expect(screen.getByRole("button", { name: /speichern/i })).toBeTruthy();
+    expect(screen.queryByText(/Read-only/)).toBeNull();
+  });
+
+  test("Editor-Role sieht Read-only-Banner + KEIN Save-Button", () => {
+    // Das ist der advisor-flagged Pfad — bisher unverifiziert. Editor-
+    // Role hat in publicstatus's Schema Zugriff auf visual-Workspace +
+    // by-slug-query (read), aber NICHT auf set.write. UI muss das
+    // explizit kommunizieren statt 403 erst beim save zu zeigen.
+    vi.mocked(useShellUser).mockReturnValue({ id: "u1", roles: ["Editor"] });
+    const Editor = getEditor();
+    render(<Editor target={TARGET} onClose={() => {}} />, { wrapper: Wrapper });
+
+    expect(screen.getByText(/Read-only/)).toBeTruthy();
+    expect(screen.queryByRole("button", { name: /^speichern/i })).toBeNull();
+  });
+
+  test("Admin-Role (publicstatus-Convention, ohne TenantAdmin-dual-Tag) sieht Read-only-Banner", () => {
+    // Apps die NUR `Admin` (ohne `TenantAdmin`) im JWT haben, kriegen
+    // read-only. Dokumentiert das Dual-Role-Pattern aus publicstatus:
+    // wer "Admin" allein hat (Memory `[Role-Naming-Drift]`), muss
+    // explizit auch "TenantAdmin" im JWT tragen damit der Editor
+    // schreiben darf.
+    vi.mocked(useShellUser).mockReturnValue({ id: "u1", roles: ["Admin"] });
+    const Editor = getEditor();
+    render(<Editor target={TARGET} onClose={() => {}} />, { wrapper: Wrapper });
+
+    expect(screen.getByText(/Read-only/)).toBeTruthy();
+    expect(screen.queryByRole("button", { name: /^speichern/i })).toBeNull();
+  });
+
+  test("Logged-out (useShellUser=undefined) sieht Read-only-Banner", () => {
+    vi.mocked(useShellUser).mockReturnValue(undefined);
+    const Editor = getEditor();
+    render(<Editor target={TARGET} onClose={() => {}} />, { wrapper: Wrapper });
+
+    expect(screen.getByText(/Read-only/)).toBeTruthy();
+    expect(screen.queryByRole("button", { name: /^speichern/i })).toBeNull();
+  });
+});