@cosmicdrift/kumiko-framework 0.1.0

package/src/files/in-memory-provider.ts

@@ -0,0 +1,62 @@
+// In-memory file provider for unit tests. Not for production: nothing
+// persists across process restarts, and memory grows with every write.
+//
+// Factored out of test-files so any package can opt in (samples, downstream
+// feature tests) without re-inventing a Map-backed mock.
+
+import type { FileStorageProvider } from "./types";
+
+export type InMemoryFileProvider = FileStorageProvider & {
+  // Test-only introspection: keys currently stored. Useful for assertions
+  // like `expect(provider.keys()).toContain("tenant/foo.jpg")`.
+  keys(): readonly string[];
+  // Test-only reset between cases. beforeEach-friendly.
+  clear(): void;
+};
+
+type StoredEntry = {
+  readonly data: Uint8Array;
+  readonly mimeType?: string | undefined;
+};
+
+export function createInMemoryFileProvider(): InMemoryFileProvider {
+  const store = new Map<string, StoredEntry>();
+
+  return {
+    async write(key, data, mimeType) {
+      // Copy the buffer so the caller can reuse/mutate theirs without
+      // aliasing the stored bytes. Cheap for tests, predictable semantics.
+      store.set(key, { data: new Uint8Array(data), mimeType });
+    },
+
+    async read(key) {
+      const entry = store.get(key);
+      if (!entry) throw new Error(`in-memory file not found: ${key}`);
+      return new Uint8Array(entry.data);
+    },
+
+    async delete(key) {
+      store.delete(key);
+    },
+
+    async exists(key) {
+      return store.has(key);
+    },
+
+    // Deterministic fake URL — encodes the key + expiry so tests can assert
+    // the route wired through without running a real presigner. Shape
+    // (memory://<key>?expires=<seconds>) intentionally differs from any real
+    // provider so leakage into production would be obvious at a glance.
+    async getSignedUrl(key, expiresInSeconds) {
+      return `memory://${key}?expires=${expiresInSeconds}`;
+    },
+
+    keys() {
+      return Array.from(store.keys());
+    },
+
+    clear() {
+      store.clear();
+    },
+  };
+}

package/src/files/index.ts

@@ -0,0 +1,29 @@
+export type { FileContext, FileHandle } from "./file-handle";
+// `createFileHandle` is an implementation detail — construct handles via
+// `createFileContext(provider).ref(key)`, which is the AppContext surface.
+export { createFileContext, deriveKey } from "./file-handle";
+export { fileRefsTable } from "./file-ref-table";
+export type {
+  FileAccessDecision,
+  FileAccessGuard,
+  FileRef,
+  FileRoutesOptions,
+  FileUploadedPayload,
+} from "./file-routes";
+export {
+  createFileRoutes,
+  FILE_UPLOADED_EVENT_TYPE,
+  fileUploadedEvent,
+  fileUploadedPayloadSchema,
+} from "./file-routes";
+export type { InMemoryFileProvider } from "./in-memory-provider";
+export { createInMemoryFileProvider } from "./in-memory-provider";
+export { createLocalProvider } from "./local-provider";
+export { filesStorageTrackingFeature, tenantStorageUsageTable } from "./storage-tracking";
+export type {
+  FileMetadata,
+  FileStorageProvider,
+  FileValidationOptions,
+  SignedUrlOptions,
+} from "./types";
+export { buildStorageKey, parseMaxSize, validateFile } from "./types";

package/src/files/local-provider.ts

@@ -0,0 +1,35 @@
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { FileStorageProvider } from "./types";
+
+// Local-filesystem backend — intended for dev + tests. Production deploys
+// pick an object-store provider (S3/R2/…). mimeType is ignored here; the
+// filesystem tracks no metadata beyond what the caller stores on FileRef.
+export function createLocalProvider(basePath: string): FileStorageProvider {
+  return {
+    async write(key: string, data: Uint8Array, _mimeType?: string): Promise<void> {
+      const filePath = join(basePath, key);
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, data);
+    },
+
+    async read(key: string): Promise<Uint8Array> {
+      const filePath = join(basePath, key);
+      return readFile(filePath);
+    },
+
+    async delete(key: string): Promise<void> {
+      const filePath = join(basePath, key);
+      await rm(filePath, { force: true });
+    },
+
+    async exists(key: string): Promise<boolean> {
+      try {
+        await stat(join(basePath, key));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/src/files/storage-tracking.ts

@@ -0,0 +1,60 @@
+// Tenant storage usage — counts bytes + files per tenant from the event log.
+//
+// Tracking-only for Phase 1: no hard limit, no upload gatekeeping. Apps read
+// the row to decide what to do (show a warning, soft-throttle, bill, …).
+// Enforcement is a conscious deferred call — we want production numbers
+// before picking thresholds (see core-files.md, Architektur-Entscheidung 3).
+//
+// The MSP is packaged as its own opt-in feature so tests that don't care
+// about storage metrics don't pay for the projection-table push or the
+// consumer-cursor row. Apps that want it pass filesStorageTrackingFeature
+// into createApp / setupTestStack alongside their domain features.
+
+import { sql } from "drizzle-orm";
+import { bigint, instant, integer, table as pgTable, uuid } from "../db/dialect";
+import { defineFeature, typedPayload } from "../engine";
+import { fileUploadedEvent } from "./file-routes";
+
+// bigint in `mode: "number"` returns a JS number (safe up to 2^53 ≈ 9e15
+// bytes ≈ 8 petabytes per tenant — large enough for any practical storage
+// quota). Default "bigint" mode would hand back a bigint value, which
+// arithmetic on Drizzle's sql`` template would still accept but forces
+// callers to remember the type.
+export const tenantStorageUsageTable = pgTable("read_tenant_storage_usage", {
+  tenantId: uuid("tenant_id").primaryKey(),
+  totalBytes: bigint("total_bytes", { mode: "number" }).notNull().default(0),
+  fileCount: integer("file_count").notNull().default(0),
+  lastUpdatedAt: instant("last_updated_at").default(sql`now()`).notNull(),
+});
+
+export const filesStorageTrackingFeature = defineFeature("files-storage-tracking", (r) => {
+  r.multiStreamProjection({
+    name: "tenant-storage-usage",
+    table: tenantStorageUsageTable,
+    apply: {
+      [fileUploadedEvent.name]: async (event, tx) => {
+        const payload = typedPayload(event, fileUploadedEvent);
+
+        // UPSERT: INSERT on first upload per tenant, otherwise atomic increment.
+        // The SQL increment guarantees correctness under concurrent dispatcher
+        // runs (shouldn't happen with a single consumer, but the invariant is
+        // free and cheap — no reason to rely on serial delivery).
+        await tx
+          .insert(tenantStorageUsageTable)
+          .values({
+            tenantId: event.tenantId,
+            totalBytes: payload.size,
+            fileCount: 1,
+          })
+          .onConflictDoUpdate({
+            target: tenantStorageUsageTable.tenantId,
+            set: {
+              totalBytes: sql`${tenantStorageUsageTable.totalBytes} + ${payload.size}`,
+              fileCount: sql`${tenantStorageUsageTable.fileCount} + 1`,
+              lastUpdatedAt: sql`NOW()`,
+            },
+          });
+      },
+    },
+  });
+});

package/src/files/types.ts

@@ -0,0 +1,118 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+export type FileMetadata = {
+  readonly fileName: string;
+  readonly mimeType: string;
+  readonly size: number;
+};
+
+// Options for `getSignedUrl`. `contentDisposition` lets the caller hint the
+// browser to download-with-name vs inline-display (maps to ResponseContent-
+// Disposition on S3). Keep the option-bag small and additive; provider impls
+// that don't support a given hint should ignore it rather than error.
+export type SignedUrlOptions = {
+  readonly contentDisposition?: string;
+};
+
+// Primitive storage contract: key+bytes in, bytes out. Metadata (fileName,
+// mimeType, size) lives on the FileRef row — the provider only needs to
+// shuttle bytes. `mimeType` on write() is a hint for providers that need a
+// Content-Type header (S3/R2/…); local filesystems can ignore it.
+//
+// `getSignedUrl` is optional: object-store backends (S3/R2/GCS) implement it
+// so clients can download directly from the provider after the server has
+// checked access — offloads bandwidth and enables browser-native caching.
+// Filesystem providers leave it undefined; the route then returns 501 and
+// the client falls back to streaming via GET /files/:id. Callers must
+// feature-detect via `typeof provider.getSignedUrl === "function"`.
+export type FileStorageProvider = {
+  write(key: string, data: Uint8Array, mimeType?: string): Promise<void>;
+  read(key: string): Promise<Uint8Array>;
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  getSignedUrl?(key: string, expiresInSeconds: number, options?: SignedUrlOptions): Promise<string>;
+};
+
+export type FileValidationOptions = {
+  readonly maxSize?: string | undefined;
+  readonly accept?: readonly string[] | undefined;
+};
+
+export function parseMaxSize(maxSize: string): number {
+  const match = maxSize.match(/^(\d+)(kb|mb|gb)$/i);
+  if (!match) throw new Error(`Invalid maxSize format: "${maxSize}". Use e.g. "10mb", "500kb".`);
+  const value = Number(match[1]);
+  const unit = (match[2] ?? "").toLowerCase();
+  switch (unit) {
+    case "kb":
+      return value * 1024;
+    case "mb":
+      return value * 1024 * 1024;
+    case "gb":
+      return value * 1024 * 1024 * 1024;
+    default:
+      throw new Error(`Unknown unit: ${unit}`);
+  }
+}
+
+// Extension → acceptable MIME-type whitelist. Guards against a client
+// uploading e.g. name="x.jpg" with mimeType="application/pdf" to slip an
+// executable past the extension-only check. Kept small & conservative — add
+// entries on demand rather than importing a heavyweight mime DB.
+const EXTENSION_MIME_WHITELIST: Record<string, readonly string[]> = {
+  jpg: ["image/jpeg", "image/jpg"],
+  jpeg: ["image/jpeg", "image/jpg"],
+  png: ["image/png"],
+  gif: ["image/gif"],
+  webp: ["image/webp"],
+  svg: ["image/svg+xml"],
+  pdf: ["application/pdf"],
+  txt: ["text/plain"],
+  csv: ["text/csv", "application/csv", "text/plain"],
+  json: ["application/json", "text/json"],
+  md: ["text/markdown", "text/plain"],
+};
+
+export function validateFile(
+  metadata: FileMetadata,
+  options: FileValidationOptions,
+): string | null {
+  if (options.maxSize) {
+    const maxBytes = parseMaxSize(options.maxSize);
+    if (metadata.size > maxBytes) {
+      return `file_too_large: ${metadata.size} bytes exceeds ${options.maxSize}`;
+    }
+  }
+
+  if (options.accept && options.accept.length > 0) {
+    const ext = metadata.fileName.split(".").pop()?.toLowerCase();
+    if (!ext || !options.accept.includes(ext)) {
+      return `invalid_file_type: ".${ext}" is not in [${options.accept.join(", ")}]`;
+    }
+    // Extension passed the whitelist — now make sure the client-reported
+    // mimeType is consistent with that extension. Guards against MIME-spoofing:
+    // an attacker can't claim extension=jpg while actually uploading PDF bytes
+    // and having the mimeType reflect that.
+    const allowedMimes = EXTENSION_MIME_WHITELIST[ext];
+    if (allowedMimes && metadata.mimeType) {
+      const normalized = metadata.mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+      if (!allowedMimes.includes(normalized)) {
+        return `mime_mismatch: extension ".${ext}" does not match mimeType "${metadata.mimeType}"`;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function buildStorageKey(
+  tenantId: TenantId,
+  entityType: string,
+  entityId: number | string,
+  fieldName: string,
+  fileName: string,
+  uniqueId: string,
+): string {
+  const ext = fileName.split(".").pop() ?? "bin";
+  return `${tenantId}/${entityType}/${entityId}/${fieldName}/${uniqueId}.${ext}`;
+}

package/src/i18n/__tests__/i18n.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import { createI18n } from "../index";
+
+describe("createI18n", () => {
+  const adminFeature = defineFeature("adminUsers", (r) => {
+    r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+    r.translations({
+      keys: {
+        "nav.title": { de: "Benutzer", en: "Users" },
+        "field.email": { de: "E-Mail", en: "Email" },
+      },
+    });
+  });
+
+  const profileFeature = defineFeature("userProfile", (r) => {
+    r.translations({
+      keys: {
+        "nav.title": { de: "Profil", en: "Profile" },
+      },
+    });
+  });
+
+  test("looks up translation by prefixed key and locale", () => {
+    const registry = createRegistry([adminFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "de" });
+
+    // Keys are prefixed: featureName:key
+    expect(i18n.t("adminUsers:nav.title", "de")).toBe("Benutzer");
+    expect(i18n.t("adminUsers:nav.title", "en")).toBe("Users");
+  });
+
+  test("falls back to default locale", () => {
+    const registry = createRegistry([adminFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "de" });
+
+    expect(i18n.t("adminUsers:nav.title", "fr")).toBe("Benutzer");
+  });
+
+  test("returns key if translation not found", () => {
+    const registry = createRegistry([adminFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "de" });
+
+    expect(i18n.t("nonexistent.key", "de")).toBe("nonexistent.key");
+  });
+
+  test("different features have separate namespaces (no collision)", () => {
+    const registry = createRegistry([adminFeature, profileFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "de" });
+
+    // Same short key, different prefix — no collision
+    expect(i18n.t("adminUsers:nav.title", "de")).toBe("Benutzer");
+    expect(i18n.t("userProfile:nav.title", "de")).toBe("Profil");
+    expect(i18n.t("adminUsers:field.email", "de")).toBe("E-Mail");
+  });
+
+  test("uses default locale when none specified", () => {
+    const registry = createRegistry([adminFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "de" });
+
+    expect(i18n.t("adminUsers:nav.title")).toBe("Benutzer");
+  });
+
+  test("getAllKeys returns prefixed translation keys", () => {
+    const registry = createRegistry([adminFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "de" });
+
+    const keys = i18n.getAllKeys();
+    expect(keys).toContain("adminUsers:nav.title");
+    expect(keys).toContain("adminUsers:field.email");
+  });
+});

package/src/i18n/index.ts

@@ -0,0 +1,29 @@
+import type { Registry, TranslationKeys } from "../engine/types";
+
+export type I18nOptions = {
+  defaultLocale: string;
+};
+
+export type I18n = {
+  t(key: string, locale?: string): string;
+  getAllKeys(): string[];
+};
+
+export function createI18n(registry: Registry, options: I18nOptions): I18n {
+  const translations: TranslationKeys = registry.getAllTranslations();
+  const { defaultLocale } = options;
+
+  return {
+    t(key: string, locale?: string): string {
+      const entry = translations[key];
+      if (!entry) return key;
+
+      const resolvedLocale = locale ?? defaultLocale;
+      return entry[resolvedLocale] ?? entry[defaultLocale] ?? key;
+    },
+
+    getAllKeys(): string[] {
+      return Object.keys(translations);
+    },
+  };
+}

package/src/jobs/__tests__/job-event-trigger.integration.ts

@@ -0,0 +1,172 @@
+import type { Hono } from "hono";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { buildServer, type JwtHelper } from "../../api";
+import { createRegistry, defineFeature, type SessionUser } from "../../engine";
+import { createTestDb, createTestRedis, type TestDb, type TestRedis, TestUsers } from "../../stack";
+import { waitFor } from "../../testing";
+import { createJobRunner, type JobRunner } from "../job-runner";
+
+// --- Track job executions ---
+
+const jobExecutions: Array<{ name: string; payload: Record<string, unknown> }> = [];
+
+// --- Features ---
+
+// Feature A: has a write handler "orders:create"
+const ordersFeature = defineFeature("orders", (r) => {
+  r.writeHandler(
+    "orders:create",
+    z.object({ product: z.string(), amount: z.number() }),
+    async (event) => {
+      return {
+        isSuccess: true,
+        data: { id: 1, product: event.payload.product, amount: event.payload.amount },
+      };
+    },
+    { access: { openToAll: true } },
+  );
+});
+
+// Feature B: has a job that triggers on "orders:write:orders:create" (prefixed)
+const notificationsFeature = defineFeature("notifications", (r) => {
+  r.job(
+    "sendOrderConfirmation",
+    { trigger: { on: "orders:write:orders:create" } },
+    async (payload) => {
+      jobExecutions.push({ name: "notifications:job:send-order-confirmation", payload });
+    },
+  );
+});
+
+// Feature C: has ANOTHER job on the same event — both should fire
+const analyticsFeature = defineFeature("analytics", (r) => {
+  // Dummy handler so the trackUser job trigger has a valid target
+  r.writeHandler(
+    "users:create",
+    z.object({}),
+    async () => ({
+      isSuccess: true as const,
+      data: null,
+    }),
+    { access: { openToAll: true } },
+  );
+
+  r.job("trackOrder", { trigger: { on: "orders:write:orders:create" } }, async (payload) => {
+    jobExecutions.push({ name: "analytics:job:track-order", payload });
+  });
+
+  // Job on a different event — should NOT fire on orders.create
+  r.job("trackUser", { trigger: { on: "analytics:write:users:create" } }, async (payload) => {
+    jobExecutions.push({ name: "analytics:job:track-user", payload });
+  });
+});
+
+// --- Setup ---
+
+let testDb: TestDb;
+let testRedis: TestRedis;
+let app: Hono;
+let jwt: JwtHelper;
+let jobRunner: JobRunner;
+
+const adminUser = TestUsers.admin;
+const JWT_SECRET = "event-trigger-test-secret-minimum-32-chars!!";
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+
+  const registry = createRegistry([ordersFeature, notificationsFeature, analyticsFeature]);
+  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+
+  jobRunner = createJobRunner({
+    registry,
+    context: {},
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-event-trigger-test-${Date.now()}`,
+  });
+
+  const server = buildServer({
+    registry,
+    context: {},
+    jwtSecret: JWT_SECRET,
+    dispatcherOptions: { jobRunner },
+  });
+  app = server.app;
+  jwt = server.jwt;
+
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+// --- Helpers ---
+
+async function writeApi(user: SessionUser, type: string, payload: unknown) {
+  const token = await jwt.sign(user);
+  const res = await app.request("/api/write", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify({ type, payload }),
+  });
+  return res.json();
+}
+
+// --- Tests ---
+
+describe("event trigger: write handler fires matching jobs", () => {
+  test("orders.create triggers both notification and analytics jobs", async () => {
+    jobExecutions.length = 0;
+
+    const result = await writeApi(adminUser, "orders:write:orders:create", {
+      product: "Widget",
+      amount: 3,
+    });
+    expect(result.isSuccess).toBe(true);
+
+    // Wait for BullMQ to process
+    await waitFor(() => {
+      const notification = jobExecutions.find(
+        (e) => e.name === "notifications:job:send-order-confirmation",
+      );
+      const analytics = jobExecutions.find((e) => e.name === "analytics:job:track-order");
+
+      expect(notification).toBeDefined();
+      expect(notification?.payload["product"]).toBe("Widget");
+      expect(notification?.payload["amount"]).toBe(3);
+
+      expect(analytics).toBeDefined();
+      expect(analytics?.payload["product"]).toBe("Widget");
+    });
+  });
+
+  test("unrelated jobs do NOT fire", async () => {
+    // analytics.trackUser listens on "users:create", not "orders:create"
+    const trackUser = jobExecutions.find((e) => e.name === "analytics:job:track-user");
+    expect(trackUser).toBeUndefined();
+  });
+
+  test("multiple orders each trigger jobs independently", async () => {
+    jobExecutions.length = 0;
+
+    await writeApi(adminUser, "orders:write:orders:create", { product: "A", amount: 1 });
+    await writeApi(adminUser, "orders:write:orders:create", { product: "B", amount: 2 });
+
+    await waitFor(() => {
+      const notifications = jobExecutions.filter(
+        (e) => e.name === "notifications:job:send-order-confirmation",
+      );
+      expect(notifications.length).toBe(2);
+
+      const products = notifications.map((e) => e.payload["product"]);
+      expect(products).toContain("A");
+      expect(products).toContain("B");
+    });
+  });
+});