@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/files-post-processing.md

@@ -0,0 +1,433 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/files-post-processing. Do not edit. -->
+
+# files-post-processing
+
+The three ways to generate an image variant: declarative field variants, imperative ctx.derivatives.variant() with region-blur, and the public route behind a default-deny predicate.
+
+## README
+
+# Files Post Processing
+
+File upload plus post-processing hooks.
+
+## What it shows
+
+- Declarative `variants` on `createImageField` (file-derivatives)
+- Imperative `ctx.derivatives.variant()` path and the public variant route (`EXT_DERIVATIVE_PUBLIC_PREDICATE`)
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/files-post-processing
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Files Post-Processing Sample — Integration Test
+//
+// Proves each of the three variant entry points end-to-end, through real
+// HTTP calls and a real sharp render (no identity-transform, no mocks):
+//
+//   1. declarative — GET /api/files/:id/variant/:name resolves a field's
+//      declared variant.
+//   2. imperative — the `set-cover` write-handler calls
+//      ctx.derivatives.variant() directly, with a region-blur.
+//   3. public route — GET /media/:fileRefId/:variant, default-deny until a
+//      photo is explicitly published.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { derivativesSharpFeature } from "@cosmicdrift/kumiko-bundled-features/derivatives-sharp";
+import { createFileDerivativesFeature } from "@cosmicdrift/kumiko-bundled-features/file-derivatives";
+import { fileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { entityEventName } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createFilesFeature,
+  createInMemoryFileProvider,
+  type InMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  buildMultipartBody,
+  patchFileInstanceofForBunTest,
+} from "@cosmicdrift/kumiko-framework/testing";
+import sharp from "sharp";
+import { coverOrder, filesPostProcessingFeature, photoEntity, publishedPhotoIds } from "../feature";
+
+const HOST = "photos.example.com";
+const HOST_B = "photos-b.example.com";
+const FILE_REF_CREATED = entityEventName("fileRef", "created");
+
+let stack: TestStack;
+let provider: InMemoryFileProvider;
+
+const tenantId = testTenantId(1);
+const tenantIdB = testTenantId(2);
+const user = createTestUser({ id: 1, tenantId, roles: ["Admin"] });
+const userB = createTestUser({ id: 2, tenantId: tenantIdB, roles: ["Admin"] });
+
+async function jpegBytes(width: number, height: number): Promise<Uint8Array> {
+  return sharp({
+    create: { width, height, channels: 3, background: { r: 90, g: 140, b: 200 } },
+  })
+    .jpeg()
+    .toBuffer();
+}
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  provider = createInMemoryFileProvider();
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      fileFoundationFeature,
+      createFilesFeature(),
+      createFileDerivativesFeature({
+        resolveApexTenant: (host) => {
+          if (host === HOST) return tenantId;
+          if (host === HOST_B) return tenantIdB;
+          return null;
+        },
+      }),
+      derivativesSharpFeature,
+      filesPostProcessingFeature,
+    ],
+    files: { storageProvider: provider },
+  });
+  await unsafeCreateEntityTable(stack.db, photoEntity, "photo");
+});
+
+async function createPhoto(asUser: typeof user = user): Promise<string> {
+  const created = await stack.http.writeOk<{ id: string }>(
+    "files-post-processing:write:photo:create",
+    {},
+    asUser,
+  );
+  return created.id;
+}
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  provider.clear();
+  publishedPhotoIds.clear();
+  coverOrder.length = 0;
+});
+
+async function uploadPhoto(
+  attach: { entityType: string; entityId: string; fieldName: string } | null,
+  asUser: typeof user = user,
+): Promise<string> {
+  const token = await stack.jwt.sign(asUser);
+  const bytes = await jpegBytes(400, 300);
+  const fd = new FormData();
+  fd.append("file", new File([Buffer.from(bytes)], "photo.jpg", { type: "image/jpeg" }));
+  if (attach) {
+    fd.append("entityType", attach.entityType);
+    fd.append("entityId", attach.entityId);
+    fd.append("fieldName", attach.fieldName);
+  }
+  const { body, contentType } = await buildMultipartBody(fd);
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+    body,
+  });
+  expect(res.status).toBe(201);
+  const json = (await res.json()) as { id: string };
+  return json.id;
+}
+
+describe("entry point 1 — declarative field variant", () => {
+  test("GET /api/files/:id/variant/:name renders a real resized webp", async () => {
+    const photoId = await createPhoto();
+    const fileId = await uploadPhoto({
+      entityType: "photo",
+      entityId: photoId,
+      fieldName: "original",
+    });
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/webp");
+    const meta = await sharp(Buffer.from(await res.arrayBuffer())).metadata();
+    expect(meta.format).toBe("webp");
+    expect(Math.max(meta.width ?? 0, meta.height ?? 0)).toBeLessThanOrEqual(200);
+  });
+});
+
+describe("entry point 2 — imperative ctx.derivatives.variant() with region-blur", () => {
+  test("set-cover derives a variant with no field declaration involved, and tracks order", async () => {
+    const fileId = await uploadPhoto(null);
+
+    const result = await stack.http.writeOk<{ fileRefId: string; storageKey: string }>(
+      "files-post-processing:write:set-cover",
+      { fileRefId: fileId, blurRegion: { x: 0, y: 0, width: 50, height: 50 } },
+      user,
+    );
+
+    expect(coverOrder).toEqual([fileId]);
+    const bytes = await provider.read(result.storageKey);
+    const meta = await sharp(Buffer.from(bytes)).metadata();
+    expect(meta.format).toBe("webp");
+    expect(Math.max(meta.width ?? 0, meta.height ?? 0)).toBeLessThanOrEqual(800);
+  });
+});
+
+describe("entry point 3 — public route, default-deny", () => {
+  test("unpublished photo → 404", async () => {
+    const photoId = await createPhoto();
+    const fileId = await uploadPhoto({
+      entityType: "photo",
+      entityId: photoId,
+      fieldName: "original",
+    });
+
+    const res = await stack.app.request(`http://${HOST}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(404);
+  });
+
+  test("photo published via the write-handler → 200 with rendered bytes", async () => {
+    const photoId = await createPhoto();
+    const fileId = await uploadPhoto({
+      entityType: "photo",
+      entityId: photoId,
+      fieldName: "original",
+    });
+    await stack.http.writeOk("files-post-processing:write:publish", { entityId: photoId }, user);
+
+    const res = await stack.app.request(`http://${HOST}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/webp");
+  });
+
+  test("publishing tenant A's photo does not publish tenant B's photo (#1983/1)", async () => {
+    const photoIdA = await createPhoto(user);
+    const photoIdB = await createPhoto(userB);
+    const fileIdA = await uploadPhoto(
+      { entityType: "photo", entityId: photoIdA, fieldName: "original" },
+      user,
+    );
+    const fileIdB = await uploadPhoto(
+      { entityType: "photo", entityId: photoIdB, fieldName: "original" },
+      userB,
+    );
+
+    // publish accepts any entityId: tenant A names B's photo too, which must not publish it.
+    await stack.http.writeOk("files-post-processing:write:publish", { entityId: photoIdB }, user);
+    await stack.http.writeOk("files-post-processing:write:publish", { entityId: photoIdA }, user);
+
+    const resA = await stack.app.request(`http://${HOST}/media/${fileIdA}/thumb`);
+    const resB = await stack.app.request(`http://${HOST_B}/media/${fileIdB}/thumb`);
+
+    expect(resA.status).toBe(200);
+    expect(resB.status).toBe(404);
+  });
+});
+
+describe("event emission contract", () => {
+  test("fileRef.created event payload carries storageKey, not the binary", async () => {
+    const photoId = await createPhoto();
+    const fileId = await uploadPhoto({
+      entityType: "photo",
+      entityId: photoId,
+      fieldName: "original",
+    });
+
+    // Inspect the raw event row. The derivatives path already proves the
+    // payload's pointer-shape by reading through it, but this test guards
+    // the contract directly: no one accidentally adds a binary field later
+    // and explodes the events table.
+    const rows = await asRawClient(stack.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE aggregate_id = $1 AND type = $2`,
+      [fileId, FILE_REF_CREATED],
+    );
+    expect(rows.length).toBe(1);
+    const row = rows[0] as { payload: Record<string, unknown> };
+    const payload = row.payload;
+    expect(typeof payload["storageKey"]).toBe("string");
+    expect(payload["mimeType"]).toBe("image/jpeg");
+    expect(payload["data"]).toBeUndefined();
+    expect(payload["binary"]).toBeUndefined();
+    expect(payload["bytes"]).toBeUndefined();
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Files Post-Processing Sample
+//
+// The three ways to get an image variant out of a FileRef — see
+// docs/reference/core-files.md for the full write-up of the contract and
+// security model behind each.
+//
+//   1. Declarative — `original`'s `variants` map on the `photo` entity. The
+//      normal case (profile picture, hero image, floor plan): the framework
+//      resolves + caches the variant behind the auth-gated
+//      `GET /api/files/:id/variant/:name` route, no handler code needed.
+//   2. Imperative — the `set-cover` write-handler calls
+//      `ctx.derivatives.variant()` directly. This is for apps that track
+//      images as their own records (ordering, a chosen cover image) and for
+//      region-blur, whose coordinates are runtime data that can't live in a
+//      static field declaration.
+//   3. The public route with a predicate — the part people get wrong. Only
+//      entityIds explicitly marked published resolve; everything else 404s,
+//      indistinguishable from "doesn't exist".
+
+import type { DerivativePublicPredicateArgs } from "@cosmicdrift/kumiko-bundled-features/file-derivatives";
+import {
+  createEntity,
+  createImageField,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  EXT_DERIVATIVE_PUBLIC_PREDICATE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+// The `variants` map IS the whitelist the auth-gated variant route resolves
+// against — no separate registration step. Named `thumb`/`hero` on purpose:
+// the public route's fixed presets (thumb/card/hero/full, entry point 3)
+// share the name `thumb` but are a completely separate spec — same label,
+// different whitelist, different actual pixels.
+export const photoEntity = createEntity({
+  table: "files_post_processing_photos",
+  fields: {
+    original: createImageField({
+      variants: {
+        thumb: { maxEdge: 200, fit: "cover", format: "webp" },
+        hero: { maxEdge: 1200, fit: "inside", format: "webp" },
+      },
+    }),
+  },
+});
+
+// A real app would check a `published` column via the entity's read model.
+// This recipe tracks it in memory to stay a single file — the predicate
+// below is what matters, not where the flag is stored. Keyed by
+// `${tenantId}:${entityId}`, not entityId alone — two tenants can each have
+// their own entityId "p3", and an entityId-only key would leak tenant A's
+// publish state onto tenant B's photo.
+export const publishedPhotoIds = new Set<string>();
+
+// Exported so the integration test can assert the imperative path ran.
+export const coverOrder: string[] = [];
+
+export const filesPostProcessingFeature = defineFeature("files-post-processing", (r) => {
+  r.requires("file-derivatives");
+  r.entity("photo", photoEntity);
+
+  // Uploading a file to a photo's field needs the same rights as saving the
+  // photo, so the photo must exist and the uploader needs update access.
+  const photoAccess = { access: { roles: ["Admin"] } } as const;
+  r.writeHandler(defineEntityCreateHandler("photo", photoEntity, photoAccess));
+  r.writeHandler(defineEntityUpdateHandler("photo", photoEntity, photoAccess));
+  r.queryHandler(defineEntityDetailHandler("photo", photoEntity, photoAccess));
+
+  // Entry point 2 — imperative. A real app would gate this behind real
+  // roles; `openToAll` keeps the recipe's HTTP wiring to one line.
+  r.writeHandler(
+    "set-cover",
+    z.object({
+      fileRefId: z.string(),
+      // Relative to the ORIGINAL image's pixels, clamped before resize —
+      // runtime data (e.g. a detected face box), which is exactly why this
+      // can only be expressed imperatively, not in a static field def.
+      blurRegion: z
+        .object({
+          x: z.number().nonnegative(),
+          y: z.number().nonnegative(),
+          width: z.number().positive(),
+          height: z.number().positive(),
+        })
+        .optional(),
+    }),
+    async (event, ctx) => {
+      if (!ctx.derivatives) {
+        return writeFailure(
+          new InternalError({ message: "ctx.derivatives missing — is file-derivatives mounted?" }),
+        );
+      }
+      const { fileRefId, blurRegion } = event.payload;
+      const result = await ctx.derivatives.variant(
+        fileRefId,
+        {
+          maxEdge: 800,
+          fit: "cover",
+          format: "webp",
+          ...(blurRegion ? { blurRegions: [blurRegion] } : {}),
+        },
+        "cover",
+      );
+      coverOrder.push(fileRefId);
+      return { isSuccess: true as const, data: { fileRefId, storageKey: result.storageKey } };
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "demo recipe: any signed-in user may generate a cover-image derivative for " +
+            "a file; there is no per-user file ownership check in this sample",
+        },
+      },
+    },
+  );
+
+  // A real app would gate this behind real roles; `openToAll` keeps the
+  // recipe's HTTP wiring to one line.
+  r.writeHandler(
+    "publish",
+    z.object({ entityId: z.string() }),
+    async (event) => {
+      publishedPhotoIds.add(`${event.user.tenantId}:${event.payload.entityId}`);
+      return { isSuccess: true as const, data: { entityId: event.payload.entityId } };
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "demo recipe: any signed-in user may mark a photo entity published; a real " +
+            "app would replace this with a role check as noted above",
+        },
+      },
+    },
+  );
+
+  // Entry point 3 — default-deny. No registration here means every entityId
+  // 404s; a registration that returns false does the same. Only an explicit
+  // `true` serves bytes.
+  r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "photo", {
+    isPublic: ({ entityId, tenantId }: DerivativePublicPredicateArgs) =>
+      publishedPhotoIds.has(`${tenantId}:${entityId}`),
+  });
+});
+```

package/agents/examples/i18n.md

@@ -0,0 +1,166 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/i18n. Do not edit. -->
+
+# i18n
+
+Feature-scoped translations. 'Hallo' and 'Hello' in the same app.
+
+## README
+
+# i18n
+
+Feature-scoped translations — 'Hallo' and 'Hello' in the same app.
+
+## What it shows
+
+- `r.translations()` for multi-language feature keys
+- Plurals
+
+## Plurals
+
+A translation value can be a CLDR plural-forms object instead of a plain
+string. `other` is required; the rest (`zero`/`one`/`two`/`few`/`many`) only
+exist where the locale's grammar needs them:
+
+```ts illustration
+"greeting.unread_count": {
+  de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+  en: { one: "{count} unread message", other: "{count} unread messages" },
+},
+```
+
+`t(key, locale, { count })` picks the CLDR category for `count` via
+`Intl.PluralRules(locale)`, then interpolates `{count}` (and any other
+`{name}` placeholder) into the chosen form.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/i18n
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.test.ts
+
+```ts
+// i18n Sample — Unit Test (no DB needed)
+// Proves: translations registered, locale resolution, fallback to default
+// Note: keys are prefixed with feature name → "featureName:key"
+
+import { describe, expect, test } from "bun:test";
+import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { createI18n } from "@cosmicdrift/kumiko-framework/i18n";
+import { errorFeature, greetingFeature } from "../feature";
+
+const registry = createRegistry([greetingFeature, errorFeature]);
+const i18n = createI18n(registry, { defaultLocale: "de" });
+
+describe("translation lookup", () => {
+  test("returns translation for default locale", () => {
+    expect(i18n.t("greeting:greeting.welcome")).toBe("Willkommen");
+    expect(i18n.t("greeting:greeting.goodbye")).toBe("Auf Wiedersehen");
+  });
+
+  test("returns translation for specific locale", () => {
+    expect(i18n.t("greeting:greeting.welcome", "en")).toBe("Welcome");
+    expect(i18n.t("greeting:greeting.welcome", "fr")).toBe("Bienvenue");
+  });
+
+  test("falls back to default locale for unknown locale", () => {
+    expect(i18n.t("greeting:greeting.welcome", "ja")).toBe("Willkommen");
+  });
+
+  test("returns key itself for unknown translation key", () => {
+    expect(i18n.t("nonexistent.key")).toBe("nonexistent.key");
+  });
+});
+
+describe("plural forms", () => {
+  test("selects the CLDR category for the count and interpolates {count}", () => {
+    expect(i18n.t("greeting:greeting.unread_count", "en", { count: 1 })).toBe("1 unread message");
+    expect(i18n.t("greeting:greeting.unread_count", "en", { count: 5 })).toBe("5 unread messages");
+    expect(i18n.t("greeting:greeting.unread_count", "de", { count: 1 })).toBe(
+      "1 ungelesene Nachricht",
+    );
+  });
+});
+
+describe("multiple features merge translations", () => {
+  test("keys from both features available", () => {
+    expect(i18n.t("greeting:greeting.welcome")).toBe("Willkommen");
+    expect(i18n.t("errors:errors.not_found")).toBe("Nicht gefunden");
+  });
+
+  test("getAllKeys returns all registered keys", () => {
+    const keys = i18n.getAllKeys();
+    expect(keys).toContain("greeting:greeting.welcome");
+    expect(keys).toContain("greeting:greeting.goodbye");
+    expect(keys).toContain("greeting:greeting.hello_name");
+    expect(keys).toContain("errors:errors.not_found");
+    expect(keys).toContain("errors:errors.access_denied");
+    expect(keys).toHaveLength(6);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// i18n Sample
+// Shows: r.translations() for multi-language feature keys, and plural forms
+// (CLDR categories) for a count-dependent key
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const greetingFeature = defineFeature("greeting", (r) => {
+  r.translations({
+    keys: {
+      "greeting.welcome": {
+        de: "Willkommen",
+        en: "Welcome",
+        fr: "Bienvenue",
+      },
+      "greeting.goodbye": {
+        de: "Auf Wiedersehen",
+        en: "Goodbye",
+        fr: "Au revoir",
+      },
+      "greeting.hello_name": {
+        de: "Hallo, {name}!",
+        en: "Hello, {name}!",
+        fr: "Bonjour, {name}!",
+      },
+      "greeting.unread_count": {
+        de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+        en: { one: "{count} unread message", other: "{count} unread messages" },
+        pl: {
+          one: "{count} nieprzeczytana wiadomość",
+          few: "{count} nieprzeczytane wiadomości",
+          many: "{count} nieprzeczytanych wiadomości",
+          other: "{count} nieprzeczytanej wiadomości",
+        },
+      },
+    },
+  });
+});
+
+export const errorFeature = defineFeature("errors", (r) => {
+  r.translations({
+    keys: {
+      "errors.not_found": {
+        de: "Nicht gefunden",
+        en: "Not found",
+      },
+      "errors.access_denied": {
+        de: "Zugriff verweigert",
+        en: "Access denied",
+      },
+    },
+  });
+});
+```