@cosmicdrift/kumiko-framework 0.1.0

package/src/files/__tests__/file-field-column.integration.ts

@@ -0,0 +1,103 @@
+// Regression test for the file/image entity-column type: must be UUID to
+// match fileRefsTable.id (uuid). Pre-fix the column was `integer`, which
+// silently blocked any client from storing a fileRef reference on the
+// entity — UUID → integer cast raised a PG error or truncated.
+//
+// Intentionally a minimal dedicated suite rather than a case in
+// files.integration.ts because the bug is about *table generation*, not
+// runtime behaviour of the upload route.
+
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createEntity, createFileField, createImageField } from "../../engine";
+import { createEntityTable, createTestDb, pushTables, type TestDb } from "../../stack";
+import { generateId } from "../../utils";
+import { fileRefsTable } from "../file-ref-table";
+
+// Entity with BOTH singular file-field types exercised — the bug applied
+// identically to `file` and `image` (same switch-case in table-builder).
+const documentEntity = createEntity({
+  table: "regression_documents",
+  fields: {
+    attachment: createFileField(),
+    cover: createImageField(),
+  },
+});
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await pushTables(testDb.db, { fileRefsTable });
+  await createEntityTable(testDb.db, documentEntity);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("file-field entity-column type", () => {
+  test("`file` and `image` fields generate UUID columns (not integer)", async () => {
+    // Pull the actual column type from information_schema. This is the
+    // load-bearing assertion: the type emitted by drizzle-kit during
+    // `createEntityTable` must be `uuid`. A regression to `integer` would
+    // fail here even if higher-level code happened to still work through
+    // implicit casts.
+    const rows = await testDb.db.execute<{ column_name: string; data_type: string }>(sql`
+      SELECT column_name, data_type
+      FROM information_schema.columns
+      WHERE table_name = 'regression_documents'
+        AND column_name IN ('attachment', 'cover')
+      ORDER BY column_name
+    `);
+    const arr = rows as unknown as Array<{ column_name: string; data_type: string }>;
+    expect(arr).toEqual([
+      { column_name: "attachment", data_type: "uuid" },
+      { column_name: "cover", data_type: "uuid" },
+    ]);
+  });
+
+  test("storing a fileRef UUID in a file-field column round-trips cleanly", async () => {
+    // Seed a fileRef row so we have a real UUID to reference. Full upload
+    // flow isn't exercised here — we're verifying the CRUD column contract.
+    const fileUuid = generateId();
+    const tenantId = generateId();
+    await testDb.db.execute(sql`
+      INSERT INTO file_refs (id, tenant_id, storage_key, file_name, mime_type, size)
+      VALUES (
+        ${fileUuid}::uuid, ${tenantId}::uuid, 'seed-key',
+        'seed.pdf', 'application/pdf', 1024
+      )
+    `);
+
+    const docId = generateId();
+    await testDb.db.execute(sql`
+      INSERT INTO regression_documents (id, tenant_id, attachment, cover)
+      VALUES (
+        ${docId}::uuid, ${tenantId}::uuid,
+        ${fileUuid}::uuid, ${fileUuid}::uuid
+      )
+    `);
+
+    const read = await testDb.db.execute<{ attachment: string; cover: string }>(sql`
+      SELECT attachment, cover FROM regression_documents WHERE id = ${docId}::uuid
+    `);
+    const docArr = read as unknown as Array<{ attachment: string; cover: string }>;
+    expect(docArr[0]?.attachment).toBe(fileUuid);
+    expect(docArr[0]?.cover).toBe(fileUuid);
+  });
+
+  test("storing a non-UUID value in a file-field column rejects — proves strict typing", async () => {
+    // If the column were still `integer`, `'not-a-uuid'` would either
+    // truncate or coerce to 0. With uuid the insert raises
+    // invalid_text_representation (22P02) — the type is actually enforced.
+    const docId = generateId();
+    const tenantId = generateId();
+    await expect(
+      testDb.db.execute(sql`
+        INSERT INTO regression_documents (id, tenant_id, attachment)
+        VALUES (${docId}::uuid, ${tenantId}::uuid, 'not-a-uuid')
+      `),
+    ).rejects.toThrow();
+  });
+});

package/src/files/__tests__/file-field-pipeline.integration.ts

@@ -0,0 +1,211 @@
+// End-to-end regression for file/image-field wiring through the CRUD
+// pipeline. The column-level fix in table-builder.ts is necessary but not
+// sufficient: the Zod validation layer in schema-builder.ts also had a
+// residual `z.number()` for file/image fields from an earlier era. Without
+// that fix the pipeline would reject every valid UUID at the validation
+// gate, before the column type ever mattered.
+//
+// This suite proves the whole path works end-to-end:
+//   POST /api/files → upload → receive file UUID
+//   POST /api/write → entity:create with file-field: <uuid>
+//   POST /api/query → entity:detail → UUID round-trips
+//   POST /api/write → entity:update with new file-UUID
+//   POST /api/query → entity:detail → new UUID persisted
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import {
+  createEntity,
+  createFileField,
+  createFilesField,
+  createImageField,
+  createImagesField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+} from "../../engine";
+import {
+  createEntityTable,
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "../../stack";
+import { createLocalProvider } from "../local-provider";
+
+// Covers ALL four file-field variants: singular (file/image) stores a UUID in
+// the entity column; plural (files/images) has no entity column — the array
+// of UUIDs lives in the event payload only (resolved via fileRefs otherwise).
+// Both shapes must validate + round-trip through the CRUD pipeline.
+const documentEntity = createEntity({
+  table: "pipeline_documents",
+  fields: {
+    title: createTextField({ required: true }),
+    attachment: createFileField(),
+    cover: createImageField(),
+    photos: createImagesField(),
+    docs: createFilesField(),
+  },
+});
+
+const ROLES = { access: { roles: ["Admin", "User"] } } as const;
+
+const documentFeature = defineFeature("pipeline-documents", (r) => {
+  r.entity("document", documentEntity);
+  r.writeHandler(defineEntityCreateHandler("document", documentEntity, ROLES));
+  r.writeHandler(defineEntityUpdateHandler("document", documentEntity, ROLES));
+  r.queryHandler(defineEntityDetailHandler("document", documentEntity, ROLES));
+});
+
+let stack: TestStack;
+let storagePath: string;
+
+const tenantId = testTenantId(1);
+const user = createTestUser({ id: 1, tenantId, roles: ["Admin"] });
+
+beforeAll(async () => {
+  storagePath = await mkdtemp(join(tmpdir(), "kumiko-file-field-pipeline-"));
+  stack = await setupTestStack({
+    features: [documentFeature],
+    files: { storageProvider: createLocalProvider(storagePath) },
+  });
+  await createEntityTable(stack.db, documentEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+  await rm(storagePath, { recursive: true, force: true });
+});
+
+beforeEach(async () => {
+  await stack.db.execute(sql`TRUNCATE pipeline_documents`);
+});
+
+async function uploadFile(fileName: string, body: Uint8Array, mimeType: string): Promise<string> {
+  const token = await stack.jwt.sign(user);
+  const fd = new FormData();
+  fd.append("file", new File([Buffer.from(body)], fileName, { type: mimeType }));
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+    body: fd,
+  });
+  // File-routes return 201 Created on successful upload.
+  expect(res.status).toBe(201);
+  const json = (await res.json()) as { id: string };
+  return json.id;
+}
+
+describe("file/image field through the CRUD pipeline", () => {
+  test("create entity with file-field UUID → detail round-trips the UUID", async () => {
+    const fileId = await uploadFile("doc.pdf", new Uint8Array([1, 2, 3]), "application/pdf");
+    const imageId = await uploadFile("cover.png", new Uint8Array([4, 5, 6]), "image/png");
+
+    // Create through the standard write pipeline — this is the path where the
+    // pre-fix validation (z.number() for file/image) would have rejected the
+    // UUID with a zod error. If we get past this, both schema + column agree.
+    const created = await stack.http.writeOk<{ id: string }>(
+      "pipeline-documents:write:document:create",
+      { title: "Annual report", attachment: fileId, cover: imageId },
+      user,
+    );
+
+    const detail = await stack.http.queryOk<{
+      id: string;
+      title: string;
+      attachment: string;
+      cover: string;
+    }>("pipeline-documents:query:document:detail", { id: created.id }, user);
+
+    expect(detail).toMatchObject({
+      id: created.id,
+      title: "Annual report",
+      attachment: fileId,
+      cover: imageId,
+    });
+  });
+
+  test("update entity swaps file-field UUIDs cleanly", async () => {
+    const oldFile = await uploadFile("v1.pdf", new Uint8Array([1]), "application/pdf");
+    const newFile = await uploadFile("v2.pdf", new Uint8Array([2]), "application/pdf");
+
+    const created = await stack.http.writeOk<{ id: string }>(
+      "pipeline-documents:write:document:create",
+      { title: "Swap target", attachment: oldFile },
+      user,
+    );
+
+    await stack.http.writeOk(
+      "pipeline-documents:write:document:update",
+      { id: created.id, version: 1, changes: { attachment: newFile } },
+      user,
+    );
+
+    const detail = await stack.http.queryOk<{ attachment: string }>(
+      "pipeline-documents:query:document:detail",
+      { id: created.id },
+      user,
+    );
+    expect(detail.attachment).toBe(newFile);
+  });
+
+  test("invalid UUID rejected by validation (code=validation_error, not some other failure)", async () => {
+    // With the pre-fix z.number() this would have returned "expected number".
+    // With z.uuid() we get a proper uuid-format error. Assertion has to pin
+    // the specific failure-class — otherwise a DB error, access-denied, or
+    // any other throw would silently satisfy `toBeDefined()` and we'd miss
+    // a regression where the validation layer stopped firing at all.
+    const err = await stack.http.writeErr(
+      "pipeline-documents:write:document:create",
+      { title: "Invalid", attachment: "not-a-uuid" },
+      user,
+    );
+    expect(err.code).toBe("validation_error");
+  });
+
+  test("plural files/images fields accept arrays of UUIDs end-to-end", async () => {
+    // Plural variants have NO entity-column (table-builder returns {} for
+    // files/images) — the array of UUIDs lives in the event payload. The
+    // pipeline still has to validate + accept it. Pre-fix this was
+    // z.array(z.number()) which would have rejected every UUID array.
+    const a = await uploadFile("a.jpg", new Uint8Array([1]), "image/jpeg");
+    const b = await uploadFile("b.jpg", new Uint8Array([2]), "image/jpeg");
+    const c = await uploadFile("notes.pdf", new Uint8Array([3]), "application/pdf");
+
+    const created = await stack.http.writeOk<{ id: string }>(
+      "pipeline-documents:write:document:create",
+      { title: "With arrays", photos: [a, b], docs: [c] },
+      user,
+    );
+    expect(created.id).toBeTruthy();
+
+    // Follow-up update: swap one photo out, add a second doc. Proves the
+    // update-path handles plural arrays too, not just create.
+    const d = await uploadFile("c.jpg", new Uint8Array([4]), "image/jpeg");
+    const e = await uploadFile("more.pdf", new Uint8Array([5]), "application/pdf");
+
+    const updated = await stack.http.writeOk<{ id: string }>(
+      "pipeline-documents:write:document:update",
+      { id: created.id, version: 1, changes: { photos: [a, d], docs: [c, e] } },
+      user,
+    );
+    // Version bumped by the CRUD executor → proves the write actually
+    // committed an event (not a silent no-op from validation-strip).
+    expect(updated.id).toBe(created.id);
+  });
+
+  test("plural files field rejects non-UUID element (schema validates EACH array element)", async () => {
+    const valid = await uploadFile("ok.pdf", new Uint8Array([1]), "application/pdf");
+    const err = await stack.http.writeErr(
+      "pipeline-documents:write:document:create",
+      { title: "Bad array", docs: [valid, "not-a-uuid"] },
+      user,
+    );
+    expect(err.code).toBe("validation_error");
+  });
+});

package/src/files/__tests__/file-handle.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "vitest";
+import { createFileContext, createFileHandle, deriveKey } from "../file-handle";
+import { createInMemoryFileProvider } from "../in-memory-provider";
+
+describe("deriveKey", () => {
+  test("inserts suffix before extension", () => {
+    expect(deriveKey("foo/bar.jpg", "medium")).toBe("foo/bar.medium.jpg");
+  });
+
+  test("handles keys without a slash", () => {
+    expect(deriveKey("bar.png", "thumb")).toBe("bar.thumb.png");
+  });
+
+  test("appends to keys without an extension", () => {
+    expect(deriveKey("foo/bar", "small")).toBe("foo/bar.small");
+  });
+
+  test("only splits on the last segment — earlier dots stay", () => {
+    expect(deriveKey("archive.v2/foo.jpg", "medium")).toBe("archive.v2/foo.medium.jpg");
+  });
+
+  test("handles multi-dot filenames — splits on the final extension", () => {
+    expect(deriveKey("tenant/my.photo.jpg", "thumb")).toBe("tenant/my.photo.thumb.jpg");
+  });
+});
+
+describe("FileHandle", () => {
+  test("read/write round-trip through the provider", async () => {
+    const provider = createInMemoryFileProvider();
+    const handle = createFileHandle("tenant/x.jpg", provider);
+
+    const payload = new Uint8Array([1, 2, 3, 4]);
+    await handle.write(payload, "image/jpeg");
+
+    const read = await handle.read();
+    expect(Array.from(read)).toEqual([1, 2, 3, 4]);
+  });
+
+  test("exists reflects write/delete state", async () => {
+    const provider = createInMemoryFileProvider();
+    const handle = createFileHandle("tenant/x.jpg", provider);
+
+    expect(await handle.exists()).toBe(false);
+    await handle.write(new Uint8Array([9]));
+    expect(await handle.exists()).toBe(true);
+    await handle.delete();
+    expect(await handle.exists()).toBe(false);
+  });
+
+  test("derive produces an independent handle at the derived key", async () => {
+    const provider = createInMemoryFileProvider();
+    const original = createFileHandle("tenant/photo.jpg", provider);
+    const thumb = original.derive("thumb");
+
+    expect(thumb.key).toBe("tenant/photo.thumb.jpg");
+
+    await original.write(new Uint8Array([1, 2]));
+    await thumb.write(new Uint8Array([9, 9, 9]));
+
+    expect(Array.from(await original.read())).toEqual([1, 2]);
+    expect(Array.from(await thumb.read())).toEqual([9, 9, 9]);
+    // Deleting the derived handle must not touch the original.
+    await thumb.delete();
+    expect(await original.exists()).toBe(true);
+  });
+
+  test("writes copy the buffer — caller mutations don't corrupt stored data", async () => {
+    const provider = createInMemoryFileProvider();
+    const handle = createFileHandle("tenant/x.bin", provider);
+
+    const buf = new Uint8Array([1, 2, 3]);
+    await handle.write(buf);
+    buf[0] = 99;
+
+    const read = await handle.read();
+    expect(Array.from(read)).toEqual([1, 2, 3]);
+  });
+});
+
+describe("createFileContext", () => {
+  test("ref returns a handle bound to the given key", async () => {
+    const provider = createInMemoryFileProvider();
+    const files = createFileContext(provider);
+
+    const h = files.ref("tenant/foo.pdf");
+    expect(h.key).toBe("tenant/foo.pdf");
+    await h.write(new Uint8Array([7]));
+
+    // Same key, new ref — should see the same stored bytes.
+    const h2 = files.ref("tenant/foo.pdf");
+    expect(Array.from(await h2.read())).toEqual([7]);
+  });
+});
+
+describe("InMemoryFileProvider", () => {
+  test("keys() lists every stored key", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("a/x.jpg", new Uint8Array([1]));
+    await provider.write("b/y.png", new Uint8Array([2]));
+    expect([...provider.keys()].sort()).toEqual(["a/x.jpg", "b/y.png"]);
+  });
+
+  test("read on a missing key throws with the key in the message", async () => {
+    const provider = createInMemoryFileProvider();
+    await expect(provider.read("nope.jpg")).rejects.toThrow(/nope\.jpg/);
+  });
+
+  test("clear() empties the store", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("a.jpg", new Uint8Array([1]));
+    provider.clear();
+    expect(provider.keys()).toEqual([]);
+    expect(await provider.exists("a.jpg")).toBe(false);
+  });
+
+  test("overwrite replaces bytes in place", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("a.jpg", new Uint8Array([1, 2]));
+    await provider.write("a.jpg", new Uint8Array([9, 9, 9]));
+    expect(Array.from(await provider.read("a.jpg"))).toEqual([9, 9, 9]);
+  });
+});