kempo-media 0.2.3

package/tests/media-api-contract.node-test.js

@@ -0,0 +1,363 @@
+import { spawn, execFileSync } from 'child_process';
+import { writeFile, mkdir, rm, readFile, stat } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { sql, eq } from 'drizzle-orm';
+
+/*
+  Drives a real kempo-server instance, with this extension actually installed, over HTTP — the
+  thing tests/uploads.node-test.js does not cover, since it calls storeUpload/parseMultipart
+  directly and never touches public/api/media/*.js. That gap was not theoretical: a 401-vs-403 bug
+  in these exact routes (a bad session cookie answering 403 instead of 401) was only ever caught by
+  hand-curling the running demo, not by any automated test — this suite exists so that class of bug
+  fails a `npm test` run instead.
+
+  Requires a reachable Postgres with kempo's core schema and this extension's own applied (see
+  drizzle.config.js). Skips itself with a clear message when there is none, so a checkout without
+  one still runs `npm test` cleanly.
+*/
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KEMPO_DIR = path.join(root, 'node_modules', 'kempo');
+
+const db = (await import(pathToFileURL(path.join(KEMPO_DIR, 'server/db/index.js')).href)).default;
+const {
+  user, userGroup, session, extension: extensionTable, kempoMediaAsset,
+} = await (async () => {
+  const kempoSchema = await import(pathToFileURL(path.join(KEMPO_DIR, 'server/db/schema.js')).href);
+  const ownSchema = await import(pathToFileURL(path.join(root, 'server/db/schema.js')).href);
+  return { ...kempoSchema, extension: kempoSchema.extension, ...ownSchema };
+})();
+
+const { createUser, addUserToGroup, installExtension, uninstallExtension } =
+  await import(pathToFileURL(path.join(KEMPO_DIR, 'server/sdk.js')).href);
+
+const databaseReachable = await db.execute(sql`select 1`).then(() => true).catch(() => false);
+
+const ADMIN = { name: 'Media Contract Admin', email: 'media-contract-admin@test.local', password: 'MediaContractAdmin123!' };
+const MEMBER = { name: 'Media Contract Member', email: 'media-contract-member@test.local', password: 'MediaContractMember123!' };
+// Member of kempo-media:editor — the group this extension actually declares (browse+upload+update,
+// deliberately not delete). Nothing else in this suite exercises that this group's own grants work.
+const EDITOR = { name: 'Media Contract Editor', email: 'media-contract-editor@test.local', password: 'MediaContractEditor123!' };
+
+const state = { server: null, port: null, tmp: null, cookies: {}, uploadedId: null };
+
+const skipped = reason => ({
+  'media api contract (SKIPPED)': async ({ pass }) => pass(`skipped: ${reason}`),
+});
+
+const purgeUsers = async () => {
+  for(const email of [ADMIN.email, MEMBER.email, EDITOR.email]){
+    const [row] = await db.select().from(user).where(eq(user.email, email));
+    if(!row) continue;
+    /*
+      kempoMediaAsset.uploadedBy has no foreign key to user.id — deleting the user first would
+      leave orphaned rows pointing at an id nothing owns. Only the admin fixture uploads in this
+      suite, but this runs unconditionally so a future fixture that also uploads is covered too.
+    */
+    await db.delete(kempoMediaAsset).where(eq(kempoMediaAsset.uploadedBy, row.id)).catch(() => {});
+    await db.delete(session).where(eq(session.userId, row.id)).catch(() => {});
+    await db.delete(userGroup).where(eq(userGroup.userId, row.id)).catch(() => {});
+    await db.delete(user).where(eq(user.id, row.id)).catch(() => {});
+  }
+};
+
+/*
+  installExtension resolves the package via <cwd>/node_modules/kempo-media, so this repo needs to
+  be able to find itself there — a self-referential junction, exactly like a real site's
+  node_modules/kempo-media would point at this exact package. Idempotent: safe to call on a
+  checkout that already has it from a previous run.
+*/
+const ensureSelfLink = async () => {
+  const link = path.join(root, 'node_modules', 'kempo-media');
+  try {
+    const stats = await stat(link);
+    if(stats.isDirectory()) return; // junction already present and resolving
+  } catch { /* fall through and create it */ }
+  const { symlink } = await import('fs/promises');
+  await rm(link, { recursive: true, force: true }).catch(() => {});
+  await symlink(root, link, 'junction');
+};
+
+/*
+  Deliberately never purgeData:true here. That drops the kempoMediaAsset table itself — fine in
+  isolation, but this suite shares one database and one test process with
+  media-data-layer.node-test.js, and a dropped table under it is not "this file's tests failed",
+  it is every other file's tests failing too. The table's lifecycle belongs to the schema push
+  (drizzle.config.js), not to a single suite's cleanup. Un-purged uninstall still removes the
+  extension's own registration/hooks, which is all re-running install needs to be idempotent.
+*/
+const purgeExtension = async () => {
+  await uninstallExtension({ name: 'kempo-media' }).catch(() => {});
+  await db.delete(extensionTable).where(eq(extensionTable.name, 'kempo-media')).catch(() => {});
+};
+
+const randomPort = () => 10000 + Math.floor(Math.random() * 20000);
+
+const waitForServer = async port => {
+  for(let i = 0; i < 100; i++){
+    try {
+      await fetch(`http://127.0.0.1:${port}/login`);
+      return true;
+    } catch {
+      await new Promise(r => setTimeout(r, 200));
+    }
+  }
+  return false;
+};
+
+const login = async ({ email, password }) => {
+  const res = await fetch(`http://127.0.0.1:${state.port}/kempo/api/auth/login/email`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+    redirect: 'manual',
+  });
+  const cookie = res.headers.get('set-cookie') || '';
+  return cookie.match(/session_token=([^;]+)/)?.[1] || null;
+};
+
+const req = async (method, urlPath, { as, body, headers = {} } = {}) => {
+  const finalHeaders = { ...headers };
+  if(as && state.cookies[as]) finalHeaders.cookie = `session_token=${state.cookies[as]}`;
+  const opts = { method, headers: finalHeaders, redirect: 'manual', signal: AbortSignal.timeout(8000) };
+  if(body !== undefined){
+    if(body instanceof FormData){
+      opts.body = body; // fetch sets its own multipart Content-Type + boundary
+    } else {
+      finalHeaders['Content-Type'] = 'application/json';
+      opts.body = JSON.stringify(body);
+    }
+  }
+  const res = await fetch(`http://127.0.0.1:${state.port}${urlPath}`, opts);
+  const json = await res.json().catch(() => null);
+  return { status: res.status, json };
+};
+
+/*
+  A tiny real PNG (1x1, red), built by hand rather than depending on sharp here — this suite is
+  about the HTTP layer, not image encoding, and a minimal-but-valid file is enough to exercise
+  storage + thumbnailing through the real route.
+*/
+const PNG_1X1_RED = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=',
+  'base64'
+);
+
+const buildTests = () => {
+  return {
+    'a server boots, all fixture accounts can sign in, and kempo-media is installed': async ({ pass, fail }) => {
+      await purgeUsers();
+      await purgeExtension();
+      await ensureSelfLink();
+
+      /*
+        Seeds system:Administrators / system:admin:access. Idempotent, run here rather than as a CI
+        step so the suite needs nothing but a database with the schema applied. It calls
+        process.exit, hence a subprocess rather than an import.
+      */
+      try {
+        execFileSync(process.execPath, [path.join(KEMPO_DIR, 'scripts', 'init-db.js')], {
+          cwd: root,
+          stdio: 'ignore',
+          env: { ...process.env },
+        });
+      } catch(e) {
+        return fail(`could not seed system groups and permissions: ${e.message}`);
+      }
+
+      const [installError] = await installExtension({ name: 'kempo-media' });
+      if(installError) return fail(`could not install kempo-media: ${installError.msg}`);
+
+      const [adminErr, adminResult] = await createUser({ ...ADMIN, emailVerified: true });
+      if(adminErr) return fail(`could not create admin fixture: ${adminErr.msg}`);
+      const [groupErr] = await addUserToGroup(adminResult.user.id, 'system:Administrators');
+      if(groupErr) return fail(`could not grant admin: ${groupErr.msg}`);
+
+      const [memberErr] = await createUser({ ...MEMBER, emailVerified: true });
+      if(memberErr) return fail(`could not create member fixture: ${memberErr.msg}`);
+
+      const [editorErr, editorResult] = await createUser({ ...EDITOR, emailVerified: true });
+      if(editorErr) return fail(`could not create editor fixture: ${editorErr.msg}`);
+      const [editorGroupErr] = await addUserToGroup(editorResult.user.id, 'kempo-media:editor');
+      if(editorGroupErr) return fail(`could not grant kempo-media:editor: ${editorGroupErr.msg}`);
+
+      /*
+        state.tmp stands in for a real site's project root: its own public/ and — critically — its
+        own node_modules, symlinked rather than installed. This matters because public/api/media/
+        POST.js resolves its storage directory as join(process.cwd(), 'public'), the same way every
+        route in this codebase does, since in a real deployment cwd is always the site root that
+        kempo-server was launched from. Spawning the server with cwd elsewhere (kempo-media's own
+        repo root, purely to make node_modules resolve) silently breaks that — uploads succeed and
+        report a path, but the bytes land next to this repo's own package.json, not under state.tmp.
+      */
+      state.tmp = path.join(root, 'tests', '.tmp-media-contract');
+      await mkdir(path.join(state.tmp, 'public', 'media', 'uploads'), { recursive: true });
+      await mkdir(path.join(state.tmp, 'public', 'media', 'thumbnails'), { recursive: true });
+      await rm(path.join(state.tmp, 'node_modules'), { recursive: true, force: true }).catch(() => {});
+      await (await import('fs/promises')).symlink(path.join(root, 'node_modules'), path.join(state.tmp, 'node_modules'), 'junction');
+
+      // Resolves against rootPath (state.tmp/public/) — one directory up reaches state.tmp/node_modules.
+      await writeFile(path.join(state.tmp, 'contract.config.json'), JSON.stringify({
+        customRoutes: { '/kempo/**': '../node_modules/kempo/dist/kempo/**' },
+        middleware: { custom: ['../node_modules/kempo/middleware/kempo.js'] },
+        templating: { ssr: true, ssrPriority: true, preRender: false },
+      }, null, 2));
+
+      state.port = randomPort();
+      state.server = spawn(process.execPath, [
+        path.join(root, 'node_modules', 'kempo-server', 'dist', 'index.js'),
+        '--root', path.join(state.tmp, 'public'),
+        '--config', path.join(state.tmp, 'contract.config.json'),
+        '--port', String(state.port),
+      ], { cwd: state.tmp, stdio: 'ignore' });
+
+      if(!await waitForServer(state.port)) return fail(`server did not start on port ${state.port}`);
+
+      state.cookies.invalid = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+      state.cookies.admin = await login(ADMIN);
+      state.cookies.member = await login(MEMBER);
+      state.cookies.editor = await login(EDITOR);
+      if(!state.cookies.admin) return fail('admin could not sign in');
+      if(!state.cookies.member) return fail('member could not sign in');
+      if(!state.cookies.editor) return fail('editor could not sign in');
+      pass();
+    },
+
+    /*
+      Each row is a permission boundary someone could quietly move. The two 401 rows and the 403
+      row are the exact distinction the bug this suite exists for got wrong: no session and an
+      invalid session both mean "authenticate and retry" (401); a valid session lacking the
+      permission means retrying will not help (403).
+    */
+    'GET /kempo-media/api/media answers the status its audience should see': async ({ pass, fail }) => {
+      if(!state.port) return fail('server did not start');
+      const cases = [
+        [null, 401], ['invalid', 401], ['member', 403], ['admin', 200],
+      ];
+      const failures = [];
+      for(const [as, expected] of cases){
+        const { status } = await req('GET', '/kempo-media/api/media', { as });
+        if(status !== expected) failures.push(`as ${as ?? 'anonymous'}: expected ${expected}, got ${status}`);
+      }
+      if(failures.length) return fail(failures.join('; '));
+      pass();
+    },
+
+    'PATCH and DELETE answer 401/401/403 the same way for a request with no target yet': async ({ pass, fail }) => {
+      if(!state.port) return fail('server did not start');
+      const failures = [];
+      for(const method of ['PATCH', 'DELETE']){
+        for(const [as, expected] of [[null, 401], ['invalid', 401], ['member', 403]]){
+          const { status } = await req(method, '/kempo-media/api/media', { as, body: { id: 'does-not-matter-yet' } });
+          if(status !== expected) failures.push(`${method} as ${as ?? 'anonymous'}: expected ${expected}, got ${status}`);
+        }
+      }
+      if(failures.length) return fail(failures.join('; '));
+      pass();
+    },
+
+    'a member without media:upload is rejected before any bytes are parsed': async ({ pass, fail }) => {
+      if(!state.port) return fail('server did not start');
+      const form = new FormData();
+      form.append('file', new Blob([PNG_1X1_RED], { type: 'image/png' }), 'x.png');
+      const { status } = await req('POST', '/kempo-media/api/media', { as: 'member', body: form });
+      if(status !== 403) return fail(`expected 403, got ${status}`);
+      pass();
+    },
+
+    'an admin can upload a real file over HTTP and the bytes survive intact': async ({ pass, fail }) => {
+      if(!state.port) return fail('server did not start');
+
+      const form = new FormData();
+      form.append('file', new Blob([PNG_1X1_RED], { type: 'image/png' }), 'contract-test.png');
+      form.append('alt', 'A one pixel test image');
+
+      const { status, json } = await req('POST', '/kempo-media/api/media', { as: 'admin', body: form });
+      if(status !== 201) return fail(`expected 201, got ${status}: ${JSON.stringify(json)}`);
+      if(!json?.asset?.id) return fail(`no asset in the response: ${JSON.stringify(json)}`);
+      if(json.asset.kind !== 'image') return fail(`expected kind image, got ${json.asset.kind}`);
+      if(json.asset.sizeBytes !== PNG_1X1_RED.length) return fail(`sizeBytes ${json.asset.sizeBytes} does not match the ${PNG_1X1_RED.length}-byte fixture — the body was likely mangled in transit`);
+      if(json.asset.altText !== 'A one pixel test image') return fail(`alt text wrong: ${json.asset.altText}`);
+
+      const onDisk = await readFile(path.join(state.tmp, 'public', json.asset.path));
+      if(!onDisk.equals(PNG_1X1_RED)) return fail('the file written to disk does not match what was uploaded — byte corruption in the real HTTP path');
+
+      state.uploadedId = json.asset.id;
+      pass();
+    },
+
+    'the upload is servable directly, and kempo-media:editor really does grant browse': async ({ pass, fail }) => {
+      if(!state.uploadedId) return fail('upload step did not complete');
+
+      const [row] = await db.select().from(kempoMediaAsset).where(eq(kempoMediaAsset.id, state.uploadedId));
+      if(!row) return fail('no DB row for the uploaded asset');
+
+      // Confirms the whole point of storing under the site's own public/: kempo-server's native
+      // static scanner serves it directly, with no serving code of this extension's own involved.
+      const fileRes = await fetch(`http://127.0.0.1:${state.port}/${row.path}`);
+      if(fileRes.status !== 200) return fail(`expected the uploaded file to be servable, got ${fileRes.status}`);
+
+      // kempo-media:editor grants browse+upload+update — this is the only test in the suite that
+      // exercises the group itself rather than a bare permission check
+      const editorView = await req('GET', `/kempo-media/api/media?id=${state.uploadedId}`, { as: 'editor' });
+      if(editorView.status !== 200) return fail(`editor (kempo-media:editor) should be able to view an asset, got ${editorView.status}`);
+      if(editorView.json?.asset?.id !== state.uploadedId) return fail('wrong asset returned to editor');
+
+      // member has no media:* grant at all — still denied, same as every other route
+      const memberView = await req('GET', `/kempo-media/api/media?id=${state.uploadedId}`, { as: 'member' });
+      if(memberView.status !== 403) return fail(`member with no media permissions should be denied, got ${memberView.status}`);
+      pass();
+    },
+
+    'admin can update the alt text, member without media:update cannot': async ({ pass, fail }) => {
+      if(!state.uploadedId) return fail('upload step did not complete');
+
+      const denied = await req('PATCH', '/kempo-media/api/media', { as: 'member', body: { id: state.uploadedId, altText: 'nope' } });
+      if(denied.status !== 403) return fail(`expected 403 for member, got ${denied.status}`);
+
+      const { status, json } = await req('PATCH', '/kempo-media/api/media', { as: 'admin', body: { id: state.uploadedId, altText: 'Updated over HTTP' } });
+      if(status !== 200) return fail(`expected 200, got ${status}: ${JSON.stringify(json)}`);
+      if(json?.asset?.altText !== 'Updated over HTTP') return fail(`alt text did not update: ${JSON.stringify(json)}`);
+      pass();
+    },
+
+    'member cannot delete, admin can, and the files are actually gone afterward': async ({ pass, fail }) => {
+      if(!state.uploadedId) return fail('upload step did not complete');
+
+      const [row] = await db.select().from(kempoMediaAsset).where(eq(kempoMediaAsset.id, state.uploadedId));
+      const absolutePath = path.join(state.tmp, 'public', row.path);
+      const absoluteThumb = row.thumbnailPath ? path.join(state.tmp, 'public', row.thumbnailPath) : null;
+
+      const denied = await req('DELETE', '/kempo-media/api/media', { as: 'member', body: { id: state.uploadedId } });
+      if(denied.status !== 403) return fail(`expected 403 for member, got ${denied.status}`);
+
+      const { status } = await req('DELETE', '/kempo-media/api/media', { as: 'admin', body: { id: state.uploadedId } });
+      if(status !== 200) return fail(`expected 200, got ${status}`);
+
+      const [, stillThere] = await db.select().from(kempoMediaAsset).where(eq(kempoMediaAsset.id, state.uploadedId));
+      if(stillThere) return fail('the DB row survived an admin delete');
+
+      const fileGone = await stat(absolutePath).then(() => false).catch(() => true);
+      if(!fileGone) return fail('the uploaded file was still on disk after delete');
+      if(absoluteThumb){
+        const thumbGone = await stat(absoluteThumb).then(() => false).catch(() => true);
+        if(!thumbGone) return fail('the thumbnail file was still on disk after delete');
+      }
+
+      // A route that never responds is worth naming, not the point of this suite, but 404 is
+      const { status: secondDelete } = await req('DELETE', '/kempo-media/api/media', { as: 'admin', body: { id: state.uploadedId } });
+      if(secondDelete !== 404) return fail(`deleting an already-deleted asset should 404, got ${secondDelete}`);
+
+      state.server?.kill();
+      await rm(state.tmp, { recursive: true, force: true }).catch(() => {});
+      await purgeUsers();
+      await purgeExtension();
+      pass();
+    },
+  };
+};
+
+export default databaseReachable
+  ? buildTests()
+  : skipped('no reachable database — see the "Local development" section of the README (docker compose up -d, then npx drizzle-kit push)');

package/tests/media-data-layer.node-test.js

@@ -0,0 +1,268 @@
+import { mkdtemp, rm, mkdir, writeFile, stat } from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import { sql, inArray } from 'drizzle-orm';
+import db from 'kempo/server/db/index.js';
+import { kempoMediaAsset } from '../server/db/schema.js';
+import createMediaAsset from '../server/utils/media/createMediaAsset.js';
+import getMediaAsset from '../server/utils/media/getMediaAsset.js';
+import getMediaAssets from '../server/utils/media/getMediaAssets.js';
+import updateMediaAsset from '../server/utils/media/updateMediaAsset.js';
+import deleteMediaAsset from '../server/utils/media/deleteMediaAsset.js';
+
+/*
+  Direct tests of server/utils/media/*.js against a real database — the CRUD layer every route in
+  public/api/media/ sits on top of, and which had no test coverage of its own before this: only the
+  storage/parsing layer below it (tests/uploads.node-test.js) and, indirectly, one manual curl
+  session. Kept separate from the API-contract suite (tests/media-api-contract.node-test.js) the
+  same way kempo itself keeps its own data-layer/route concerns apart — this needs a database and
+  nothing else, no server, no HTTP.
+
+  Requires a reachable Postgres with this package's schema applied (see drizzle.config.js and the
+  "Local development" section of the README). Skips itself with a clear message when there is none,
+  so a checkout without one still runs `npm test`.
+*/
+
+const databaseReachable = await db.execute(sql`select 1`).then(() => true).catch(() => false);
+
+const skipped = reason => ({
+  'media data layer (SKIPPED)': async ({ pass }) => pass(`skipped: ${reason}`),
+});
+
+const OWNER = 'test-uploader-id';
+const createdIds = [];
+
+// Every column createMediaAsset expects, so each test only needs to override what it cares about
+const fixtureAsset = (overrides = {}) => ({
+  id: crypto.randomBytes(8).toString('hex'),
+  filename: 'fixture.png',
+  originalName: 'My Photo.png',
+  mimeType: 'image/png',
+  kind: 'image',
+  sizeBytes: 1234,
+  path: 'media/uploads/fixture.png',
+  thumbnailPath: 'media/thumbnails/fixture.webp',
+  altText: '',
+  width: 100,
+  height: 80,
+  uploadedBy: OWNER,
+  ...overrides,
+});
+
+const create = async (overrides = {}) => {
+  const [error, row] = await createMediaAsset(fixtureAsset(overrides));
+  if(!error) createdIds.push(row.id);
+  return [error, row];
+};
+
+const purge = async () => {
+  if(createdIds.length){
+    await db.delete(kempoMediaAsset).where(inArray(kempoMediaAsset.id, createdIds)).catch(() => {});
+    createdIds.length = 0;
+  }
+};
+
+const withTempRoot = async fn => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'kempo-media-data-'));
+  try {
+    return await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+};
+
+const buildTests = () => ({
+  'createMediaAsset records every column and stamps timestamps': async ({ pass, fail }) => {
+    const [error, row] = await create({ altText: 'A test image' });
+    if(error) return fail(`unexpected error: ${error.msg}`);
+
+    if(row.originalName !== 'My Photo.png') return fail(`originalName wrong: ${row.originalName}`);
+    if(row.kind !== 'image') return fail(`kind wrong: ${row.kind}`);
+    if(row.altText !== 'A test image') return fail(`altText wrong: ${row.altText}`);
+    if(!(row.createdAt instanceof Date)) return fail(`createdAt is not a Date: ${row.createdAt}`);
+    if(row.createdAt.getTime() !== row.updatedAt.getTime()) return fail('createdAt and updatedAt should match on insert');
+    pass();
+  },
+
+  'getMediaAsset returns the row by id, and a 404 tuple for one that does not exist': async ({ pass, fail }) => {
+    const [, created] = await create();
+    const [error, found] = await getMediaAsset(created.id);
+    if(error) return fail(`unexpected error fetching an existing asset: ${error.msg}`);
+    if(found.id !== created.id) return fail('fetched the wrong row');
+
+    const [missingError, missing] = await getMediaAsset('0000000000000000');
+    if(missing) return fail('expected no data for a missing id');
+    if(missingError?.code !== 404) return fail(`expected a 404 tuple, got ${JSON.stringify(missingError)}`);
+    pass();
+  },
+
+  'getMediaAssets filters by a single kind': async ({ pass, fail }) => {
+    const [, image] = await create({ kind: 'image' });
+    const [, video] = await create({ kind: 'video', thumbnailPath: null, width: null, height: null });
+
+    const [error, data] = await getMediaAssets({ kind: 'video', limit: 100 });
+    if(error) return fail(`unexpected error: ${error.msg}`);
+    const ids = data.assets.map(a => a.id);
+    if(!ids.includes(video.id)) return fail('the video fixture is missing from a kind=video query');
+    if(ids.includes(image.id)) return fail('an image fixture leaked into a kind=video query');
+    pass();
+  },
+
+  'getMediaAssets filters by a comma-separated list of kinds': async ({ pass, fail }) => {
+    const [, image] = await create({ kind: 'image' });
+    const [, audio] = await create({ kind: 'audio', thumbnailPath: null, width: null, height: null });
+    const [, archive] = await create({ kind: 'archive', thumbnailPath: null, width: null, height: null });
+
+    const [error, data] = await getMediaAssets({ kind: 'image,audio', limit: 100 });
+    if(error) return fail(`unexpected error: ${error.msg}`);
+    const ids = data.assets.map(a => a.id);
+    if(!ids.includes(image.id) || !ids.includes(audio.id)) return fail('image/audio fixtures missing from the combined-kind query');
+    if(ids.includes(archive.id)) return fail('an archive fixture leaked into an image,audio query');
+    pass();
+  },
+
+  'getMediaAssets ignores an unrecognised kind rather than matching nothing silently': async ({ pass, fail }) => {
+    const [, row] = await create();
+    /*
+      A typo in a query string (?kind=iamge) should not read as "the library is empty" — that is
+      indistinguishable from a real empty state and would be a confusing UI to debug.
+    */
+    const [error, data] = await getMediaAssets({ kind: 'not-a-real-kind', limit: 100 });
+    if(error) return fail(`unexpected error: ${error.msg}`);
+    if(!data.assets.some(a => a.id === row.id)) return fail('an unrecognised kind filtered out everything instead of being ignored');
+    pass();
+  },
+
+  'getMediaAssets searches originalName, case-insensitively': async ({ pass, fail }) => {
+    const [, row] = await create({ originalName: 'Sunset-Over-Mountains.PNG' });
+    const [error, data] = await getMediaAssets({ search: 'sunset-over', limit: 100 });
+    if(error) return fail(`unexpected error: ${error.msg}`);
+    if(!data.assets.some(a => a.id === row.id)) return fail('case-insensitive substring search did not find the fixture');
+    pass();
+  },
+
+  'getMediaAssets paginates with limit/offset and reports an accurate total': async ({ pass, fail }) => {
+    const marker = crypto.randomBytes(4).toString('hex');
+    const rows = [];
+    for(let i = 0; i < 5; i++){
+      const [, row] = await create({ originalName: `page-fixture-${marker}-${i}.png` });
+      rows.push(row);
+    }
+
+    const [error, data] = await getMediaAssets({ search: `page-fixture-${marker}`, limit: 2, offset: 0 });
+    if(error) return fail(`unexpected error: ${error.msg}`);
+    if(data.total !== 5) return fail(`expected total 5, got ${data.total}`);
+    if(data.assets.length !== 2) return fail(`expected a page of 2, got ${data.assets.length}`);
+
+    const [, page2] = await getMediaAssets({ search: `page-fixture-${marker}`, limit: 2, offset: 2 });
+    if(page2.assets.length !== 2) return fail(`expected the second page to have 2, got ${page2.assets.length}`);
+    if(page2.assets.some(a => data.assets.some(first => first.id === a.id))){
+      return fail('the second page repeated a row from the first');
+    }
+    pass();
+  },
+
+  'getMediaAssets orders newest first': async ({ pass, fail }) => {
+    const marker = crypto.randomBytes(4).toString('hex');
+    const [, older] = await create({ originalName: `order-fixture-${marker}-older.png` });
+    await new Promise(r => setTimeout(r, 20));
+    const [, newer] = await create({ originalName: `order-fixture-${marker}-newer.png` });
+
+    const [error, data] = await getMediaAssets({ search: `order-fixture-${marker}`, limit: 10 });
+    if(error) return fail(`unexpected error: ${error.msg}`);
+    const ids = data.assets.map(a => a.id);
+    if(ids.indexOf(newer.id) > ids.indexOf(older.id)) return fail(`expected the newer row first, got order ${ids}`);
+    pass();
+  },
+
+  'updateMediaAsset updates altText and originalName independently': async ({ pass, fail }) => {
+    const [, row] = await create({ altText: 'before' });
+
+    const [altError, altUpdated] = await updateMediaAsset(row.id, { altText: 'after' });
+    if(altError) return fail(`unexpected error: ${altError.msg}`);
+    if(altUpdated.altText !== 'after') return fail(`altText did not update: ${altUpdated.altText}`);
+    if(altUpdated.originalName !== row.originalName) return fail('originalName changed when only altText was given');
+
+    const [nameError, nameUpdated] = await updateMediaAsset(row.id, { originalName: '  Renamed.png  ' });
+    if(nameError) return fail(`unexpected error: ${nameError.msg}`);
+    if(nameUpdated.originalName !== 'Renamed.png') return fail(`expected a trimmed name, got ${JSON.stringify(nameUpdated.originalName)}`);
+    pass();
+  },
+
+  'updateMediaAsset rejects an empty name and a no-op update': async ({ pass, fail }) => {
+    const [, row] = await create();
+
+    const [emptyError] = await updateMediaAsset(row.id, { originalName: '   ' });
+    if(emptyError?.code !== 400) return fail(`expected 400 for a blank name, got ${JSON.stringify(emptyError)}`);
+
+    const [noopError] = await updateMediaAsset(row.id, {});
+    if(noopError?.code !== 400) return fail(`expected 400 for an update with nothing to change, got ${JSON.stringify(noopError)}`);
+    pass();
+  },
+
+  'updateMediaAsset on a missing id returns a 404 tuple': async ({ pass, fail }) => {
+    const [error, data] = await updateMediaAsset('0000000000000000', { altText: 'x' });
+    if(data) return fail('expected no data for a missing id');
+    if(error?.code !== 404) return fail(`expected a 404 tuple, got ${JSON.stringify(error)}`);
+    pass();
+  },
+
+  'deleteMediaAsset removes the row and both files on disk': async ({ pass, fail }) => {
+    await withTempRoot(async rootDir => {
+      const uploadRel = 'media/uploads/delete-me.png';
+      const thumbRel = 'media/thumbnails/delete-me.webp';
+      await mkdir(path.join(rootDir, 'media', 'uploads'), { recursive: true });
+      await mkdir(path.join(rootDir, 'media', 'thumbnails'), { recursive: true });
+      await writeFile(path.join(rootDir, uploadRel), 'x');
+      await writeFile(path.join(rootDir, thumbRel), 'y');
+
+      const [, row] = await create({ path: uploadRel, thumbnailPath: thumbRel });
+      const [error] = await deleteMediaAsset(row.id, { rootDir });
+      if(error) throw new Error(`unexpected error: ${error.msg}`);
+
+      const [, stillThere] = await getMediaAsset(row.id);
+      if(stillThere) throw new Error('the row survived deleteMediaAsset');
+
+      const uploadGone = await stat(path.join(rootDir, uploadRel)).then(() => false).catch(() => true);
+      const thumbGone = await stat(path.join(rootDir, thumbRel)).then(() => false).catch(() => true);
+      if(!uploadGone) throw new Error('the uploaded file was not removed');
+      if(!thumbGone) throw new Error('the thumbnail file was not removed');
+
+      createdIds.splice(createdIds.indexOf(row.id), 1); // already gone, do not delete it again in purge()
+    });
+    pass();
+  },
+
+  'deleteMediaAsset tolerates a file already missing from disk': async ({ pass, fail }) => {
+    await withTempRoot(async rootDir => {
+      // rootDir deliberately has neither file — simulates one having been removed by hand
+      const [, row] = await create({ path: 'media/uploads/already-gone.png', thumbnailPath: 'media/thumbnails/already-gone.webp' });
+
+      const [error] = await deleteMediaAsset(row.id, { rootDir });
+      if(error) throw new Error(`a missing file should not fail the delete: ${error.msg}`);
+
+      const [, stillThere] = await getMediaAsset(row.id);
+      if(stillThere) throw new Error('the row should still be gone even though its files already were');
+
+      createdIds.splice(createdIds.indexOf(row.id), 1);
+    });
+    pass();
+  },
+
+  'deleteMediaAsset on a missing id returns a 404 tuple and touches no files': async ({ pass, fail }) => {
+    const [error, data] = await deleteMediaAsset('0000000000000000', { rootDir: os.tmpdir() });
+    if(data) return fail('expected no data for a missing id');
+    if(error?.code !== 404) return fail(`expected a 404 tuple, got ${JSON.stringify(error)}`);
+    pass();
+  },
+
+  'cleanup: fixtures are purged': async ({ pass }) => {
+    await purge();
+    pass();
+  },
+});
+
+export default databaseReachable
+  ? buildTests()
+  : skipped('no reachable database — see the "Local development" section of the README (docker compose up -d, then npx drizzle-kit push)');