kempo-media 0.3.1 → 0.3.3

package/.github/workflows/publish.yml

@@ -26,6 +26,25 @@ jobs:
     permissions:
       contents: write
       id-token: write
+    # The database-backed suites skip themselves when no database is reachable, which reads as a pass.
+    # Publishing used to run without one, so a release could go out while the test workflow was red.
+    # This is the same service and schema the test workflow uses, so the two gates agree.
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: kempo
+          POSTGRES_PASSWORD: kempo
+          POSTGRES_DB: kempo_media_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DATABASE_URL: postgresql://kempo:kempo@localhost:5432/kempo_media_test
     steps:
       - uses: actions/checkout@v4
         with:
@@ -49,9 +68,15 @@ jobs:
       - name: Install the host for the test gate
         run: npm install --no-save kempo@latest kempo-files@latest kempo-thumbs@latest kempo-ui@latest kempo-server@latest
 
-      - name: Run Unit Tests
+      - name: Apply database schema
+        run: npx drizzle-kit push --force
+
+      - name: Run unit tests
         run: npm test
 
+      - name: Run integration tests
+        run: npm run test:integration
+
       - name: Set version type
         id: version
         run: |

package/.github/workflows/test.yml

@@ -11,9 +11,30 @@ on:
       - master
 
 jobs:
-  # kempo/kempo-ui/kempo-server resolve from the registry, which is what a site installing this
-  # extension gets. Peer dependencies are installed automatically by npm ci.
-  published:
+  # Unit tier: an in-memory Postgres (PGlite), so there is no service to start and a database
+  # suite cannot skip for want of one.
+  unit:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - run: npm ci
+
+      # kempo, kempo-files, kempo-thumbs, kempo-ui and kempo-server are peer dependencies, which npm ci does not install.
+      - name: Install the host for the test gate
+        run: npm install --no-save kempo@latest kempo-files@latest kempo-thumbs@latest kempo-ui@latest kempo-server@latest
+
+      - name: Run unit tests
+        run: npm test
+
+
+  # Integration tier: the whole suite on a real Postgres. An unreachable database fails it.
+  integration:
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
     runs-on: ubuntu-latest
     services:
@@ -50,8 +71,9 @@ jobs:
       - name: Apply database schema
         run: npx drizzle-kit push --force
 
-      - name: Run Unit Tests
-        run: npm test
+      - name: Run integration tests
+        run: npm run test:integration
+
 
   # Same suite against the sibling checkout of the host. This extension resolves imports out of
   # kempo, so it breaks whenever the host moves something it reaches into — this job is what
@@ -129,6 +151,10 @@ jobs:
         run: npx drizzle-kit push --force
         working-directory: kempo-media
 
-      - name: Run Unit Tests
+      - name: Run unit tests
         run: npm test
         working-directory: kempo-media
+
+      - name: Run integration tests
+        run: npm run test:integration
+        working-directory: kempo-media

package/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+### Added
+
+- **Dashboard widget.** A **Media** widget on the kempo admin dashboard showing the asset count and the latest uploads, with a **Upload media** button, declared in `widgets` in `kempo-config.json`. Needs a kempo with the dashboard; ignored on older versions.
 ### Changed
  - **Media now sits on kempo-files, with thumbnails from kempo-thumbs.** Before, this extension kept its own copy of everything: uploads in the site's `public/media/uploads/` (static serving, no permissions), and `sharp` thumbnails in `public/media/thumbnails/`, parallel to kempo-files' permission-checked library and kempo-thumbs' ffmpeg thumbnails. Anything consuming images had to handle both stacks. Now an asset is a kempo-files file plus a `kempoMediaAsset` row (kind, dimensions, alt text, display name), the **asset id is the file id** (no mapping table), the bytes live in kempo-files' `files/media/` folder, and a thumbnail is whatever kempo-thumbs made. One storage layer, one set of file permissions, one thumbnail path.
  - `kempo-config.json` declares `"dependencies": ["kempo-files", "kempo-thumbs"]`; kempo will not install this extension until both are enabled. kempo-thumbs is required rather than optional so every consumer can rely on `thumbnail` meaning the same thing. Requires `kempo-files` >= 0.1.5, which adds `uploadFile`, caller-chosen ids and download caching.

package/README.md

@@ -158,3 +158,7 @@ npm test
 - **Only assets uploaded through this library are in it.** Other files in kempo-files do not appear in the media grid unless registered with `createMediaAsset`.
 - **A replaced public file can be cached for up to an hour** by browsers (kempo-files' cache lifetime).
 - **No usage tracking.** Deleting an asset does not check whether a page links to it.
+
+## Dashboard widget
+
+Adds a **Media** widget to the kempo admin dashboard showing the asset count and the latest uploads, with a **Upload media** button. It is declared in `widgets` in `kempo-config.json` and registered when the extension is installed or updated; people only see it if they hold its permission, and can hide, reorder or resize it from the dashboard's Customize dialog. Needs a kempo with the dashboard (see kempo's `docs/dashboard.md`); on an older kempo the entry is ignored.

package/kempo-config.json

@@ -3,6 +3,22 @@
   "public-scope": "kempo-media",
   "schema": "./server/db/schema.js",
   "dependencies": ["kempo-files", "kempo-thumbs"],
+  "widgets": [
+    {
+      "key": "library",
+      "title": "Media",
+      "description": "How many media assets there are and the latest uploads.",
+      "icon": "image",
+      "element": "k-media-widget",
+      "module": "/kempo-media/components/MediaWidget.js",
+      "defaultWidth": 2,
+      "defaultHeight": 2,
+      "minWidth": 1,
+      "minHeight": 2,
+      "permission": "media:browse",
+      "priority": 73
+    }
+  ],
   "permissions": [
     { "name": "media:browse", "description": "List and view media library assets" },
     { "name": "media:upload", "description": "Upload new media assets" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-media",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Media library extension for kempo — upload and manage images, video, audio, 3D models, and archives, stored in kempo-files with thumbnails from kempo-thumbs",
   "license": "MIT",
   "author": "Dustin Poissant",
@@ -8,7 +8,8 @@
   "main": "sdk.js",
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "kempo-test -l minimal",
+    "test": "node scripts/run-tests.js unit kempo-test -l minimal",
+    "test:integration": "node scripts/run-tests.js integration kempo-test -l minimal",
     "link:local": "npm install ../kempo ../kempo-files ../kempo-thumbs ../kempo-server ../kempo-ui --no-save --no-legacy-peer-deps --force"
   },
   "kempo": {
@@ -33,6 +34,7 @@
     "kempo-ui": ">=0.4.43"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.9",
     "drizzle-kit": "^0.31.10",
     "kempo-testing-framework": "^1.4.11",
     "postgres": "^3.4.9"

package/public/components/MediaWidget.js

@@ -0,0 +1,50 @@
+import DashboardWidget from '/kempo/components/DashboardWidget.js';
+import { html, nothing } from '/kempo-ui/lit-all.min.js';
+import { getMediaAssets } from '/kempo-media/sdk.js';
+
+/*
+  The size of the media library and the most recent uploads.
+*/
+export default class MediaWidget extends DashboardWidget {
+  static properties = {
+    ...DashboardWidget.properties,
+    total: { state: true },
+    recent: { state: true }
+  };
+
+  constructor(){
+    super();
+    this.total = 0;
+    this.recent = [];
+    this.cta = { label: 'Upload media', icon: 'upload', href: '/admin/extension/kempo-media/', permission: 'media:upload' };
+  }
+
+  /*
+    Public Methods
+  */
+
+  load = async () => {
+    const { assets, total } = await this.unwrap(getMediaAssets({ limit: 9 }));
+    this.total = total;
+    this.recent = assets;
+  };
+
+  /*
+    Rendering
+  */
+
+  renderContent(){
+    if(!this.total) return html`<p class="tc-muted">No media yet.</p>`;
+    const rows = this.recent.slice(0, this.height * 3);
+    return html`
+      <div class="h2 m0">${this.total}</div>
+      <div class="small tc-muted mb">${this.total === 1 ? 'Asset' : 'Assets'}</div>
+      ${rows.length ? html`<div class="small tc-muted mbq">Latest</div>` : nothing}
+      ${rows.map(asset => html`
+        <div class="d-f pyq bb"><span class="flex">${asset.originalName || asset.name || asset.id}</span><span class="small tc-muted">${asset.kind}</span></div>
+      `)}
+    `;
+  }
+}
+
+customElements.define('k-media-widget', MediaWidget);

package/scripts/run-tests.js

@@ -0,0 +1,47 @@
+import { spawnSync } from 'child_process';
+import { pathToFileURL } from 'url';
+import path from 'path';
+
+/*
+  The two test tiers, then the command to run in each.
+
+    unit         `KEMPO_DB=pglite`: kempo's database module gives an in-process, in-memory Postgres
+                 (PGlite) holding the tables in drizzle.config.js, so nothing external is needed and a
+                 database suite can never skip for want of one.
+    integration  a real Postgres at DATABASE_URL, for the suites that boot a second server process.
+                 Here an unreachable database fails the run instead of skipping, so it cannot look
+                 green without having run.
+
+  `npm test` is the unit tier. `npm run test:integration` runs the whole suite on a real database. CI
+  runs both.
+
+  Usage: node scripts/run-tests.js <unit|integration> <command> [arguments]
+*/
+
+const [tier, command, ...args] = process.argv.slice(2);
+
+if(!['unit', 'integration'].includes(tier) || !command){
+  console.error('Usage: node scripts/run-tests.js <unit|integration> <command> [arguments]');
+  process.exit(2);
+}
+
+const env = { ...process.env };
+
+if(tier === 'unit'){
+  env.KEMPO_DB = 'pglite';
+  delete env.KEMPO_TEST_TIER;
+  // Create the database before any test file can install globals that confuse it. See the preload.
+  const preload = pathToFileURL(path.resolve(import.meta.dirname, '..', 'tests', 'helpers', 'preload.js')).href;
+  env.NODE_OPTIONS = `${env.NODE_OPTIONS || ''} --import=${preload}`.trim();
+} else {
+  delete env.KEMPO_DB;
+  env.KEMPO_TEST_TIER = 'integration';
+  if(!env.DATABASE_URL){
+    console.error('The integration tier needs DATABASE_URL pointing at a throwaway Postgres (named *_test) with the schema applied (npx drizzle-kit push).');
+    process.exit(2);
+  }
+}
+
+const result = spawnSync(command, args, { stdio: 'inherit', env, shell: true });
+
+process.exit(result.status ?? 1);

package/tests/dashboard-widget.node-test.js

@@ -0,0 +1,85 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+/*
+  This extension adds widgets to the kempo admin dashboard through `widgets` in kempo-config.json. Core
+  refuses a definition it could not render (and the extension would fail to install), and a module path
+  that points at nothing only shows up as a broken tile, so both are checked here.
+
+  The rules are checked inline so this works against any installed kempo, including one released before
+  the dashboard existed. When the installed kempo does have the dashboard, its own validation also runs.
+*/
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const config = JSON.parse(await readFile(path.join(root, 'kempo-config.json'), 'utf8'));
+const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+const core = await import(pathToFileURL(path.join(root, 'node_modules', 'kempo', 'server', 'utils', 'dashboard', 'helpers.js')).href).catch(() => null);
+
+const scope = `/${pkg.kempo?.['public-scope'] || config['public-scope']}/`;
+const permissions = new Set((config.permissions || []).map(p => p.name));
+
+const ELEMENT = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
+const KEY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const LOCAL_PATH = /^\/(?![/\\])[^\\\s\u0000-\u001f\u007f]*$/;
+const blocks = (value, max) => Number.isInteger(value) && value >= 1 && value <= max;
+
+const problems = widget => {
+  const { key, title, element, module, defaultWidth = 2, defaultHeight = 1, minWidth = 1, maxWidth = 4, minHeight = 1, maxHeight = 3, actions = [] } = widget;
+  const found = [];
+  if(typeof key !== 'string' || !KEY.test(key)) found.push('key must be letters, numbers, ".", "_" or "-"');
+  if(typeof title !== 'string' || !title.trim() || title.length > 100) found.push('title is required, at most 100 characters');
+  if(typeof element !== 'string' || !ELEMENT.test(element)) found.push('element must be a custom element name such as "my-ext-widget"');
+  if(typeof module !== 'string' || !LOCAL_PATH.test(module)) found.push('module must be a path on this site beginning with a single "/"');
+  if(!blocks(minWidth, 4) || !blocks(maxWidth, 4) || minWidth > maxWidth) found.push('minWidth and maxWidth must be 1 to 4, min no greater than max');
+  if(!blocks(minHeight, 3) || !blocks(maxHeight, 3) || minHeight > maxHeight) found.push('minHeight and maxHeight must be 1 to 3, min no greater than max');
+  if(!Number.isInteger(defaultWidth) || defaultWidth < minWidth || defaultWidth > maxWidth) found.push('defaultWidth must be within the width bounds');
+  if(!Number.isInteger(defaultHeight) || defaultHeight < minHeight || defaultHeight > maxHeight) found.push('defaultHeight must be within the height bounds');
+  if(!Array.isArray(actions) || actions.length > 3 || actions.some(action => !action?.label || !LOCAL_PATH.test(action?.href))) found.push('actions must be at most 3 { label, href } with a site path');
+  return found;
+};
+
+export default {
+  'kempo-config.json declares at least one widget': async ({ pass, fail }) => {
+    if(!Array.isArray(config.widgets) || !config.widgets.length) return fail('no widgets declared');
+    pass(`${config.widgets.length} widget(s)`);
+  },
+
+  'every declared widget is a definition the dashboard can render': async ({ pass, fail }) => {
+    for(const widget of config.widgets){
+      const found = problems(widget);
+      if(found.length) return fail(`${widget.key}: ${found.join('; ')}`);
+      if(core){
+        const [error] = core.normalizeWidget({ ...widget, owner: pkg.name });
+        if(error) return fail(`${widget.key}: kempo core refuses it: ${error.msg}`);
+      }
+    }
+    pass(core ? 'checked inline and by kempo core' : 'checked inline');
+  },
+
+  'every widget module is served from the public scope and exists': async ({ pass, fail }) => {
+    for(const { key, module } of config.widgets){
+      if(!module.startsWith(scope)) return fail(`${key}: ${module} is outside ${scope}`);
+      if(!existsSync(path.join(root, 'public', module.slice(scope.length)))) return fail(`${key}: ${module} does not exist under public/`);
+    }
+    pass();
+  },
+
+  'a widget permission is one the extension declares, or from core or a dependency when it declares none': async ({ pass, fail }) => {
+    for(const { key, permission } of config.widgets){
+      if(permission && permissions.size && !permissions.has(permission) && !permission.startsWith('system:')){
+        return fail(`${key}: permission "${permission}" is not declared by this extension`);
+      }
+    }
+    pass();
+  },
+
+  'every widget module defines the element it is registered with': async ({ pass, fail }) => {
+    for(const { key, module, element } of config.widgets){
+      const source = await readFile(path.join(root, 'public', module.slice(scope.length)), 'utf8');
+      if(!source.includes(`customElements.define('${element}'`)) return fail(`${key}: ${module} never defines <${element}>`);
+    }
+    pass();
+  },
+};

package/tests/helpers/db.js

@@ -0,0 +1,19 @@
+/*
+  Shared by the database-backed suites. See scripts/run-tests.js for the tiers.
+*/
+
+export const unitTier = process.env.KEMPO_DB === 'pglite';
+export const integrationTier = process.env.KEMPO_TEST_TIER === 'integration';
+
+/*
+  The suite for a file that belongs to the integration tier, reported as such in the unit tier. It is
+  explicit rather than a silent skip, and `npm run test:integration` is where it runs.
+*/
+export const integrationOnly = name => ({
+  [`${name} (integration tier)`]: async ({ pass }) => pass('runs in `npm run test:integration`: it needs a real Postgres or a second server process'),
+});
+
+/*
+  Seeds kempo's system groups, permissions and settings in-process. Needs kempo >= 4.5.5.
+*/
+export const seedDatabase = async () => (await import('kempo/server/utils/setup/seedDatabase.js')).default({ log: () => {} });

package/tests/helpers/preload.js

@@ -0,0 +1,10 @@
+/*
+  Loaded with `--import` by scripts/run-tests.js in the unit tier, before any test file.
+
+  The in-memory database is created on first import of kempo's database module. Creating it here, in a
+  clean process, keeps the run from depending on which suite imports it first or on globals a test
+  file has installed by then.
+*/
+if(process.env.KEMPO_DB === 'pglite'){
+  await import('kempo/server/db/index.js');
+}

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

@@ -1,3 +1,4 @@
+import { unitTier, integrationOnly } from './helpers/db.js';
 import { spawn, execFileSync } from 'child_process';
 import { writeFile, mkdir, rm, readFile, stat } from 'fs/promises';
 import path from 'path';
@@ -465,6 +466,8 @@ const buildTests = () => {
   };
 };
 
-export default databaseReachable
+export default unitTier
+  ? integrationOnly('media API contract')
+  : 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

@@ -79,6 +79,13 @@ const purge = async () => {
   }
 };
 
+/*
+  kempo-files' media folder also lives on disk, and the disk outlives a database. A fresh in-memory
+  database has no row for a folder an earlier run left behind, so the first upload would be refused
+  ("already exists on disk"). This suite owns that folder, so start from none.
+*/
+await rm(path.join(process.cwd(), 'files', 'media'), { recursive: true, force: true }).catch(() => {});
+
 const buildTests = () => ({
   'createMediaAsset records every column and stamps timestamps': async ({ pass, fail }) => {
     const [error, row] = await create({ altText: 'A test image' });

package/tests/media-migration.node-test.js

@@ -78,6 +78,12 @@ const cleanup = async () => {
   for(const id of Object.values(IDS)) await deleteFile({ id }).catch(() => {});
   await db.delete(kempoMediaAsset).where(inArray(kempoMediaAsset.id, Object.values(IDS))).catch(() => {});
   await db.delete(settingTable).where(eq(settingTable.name, 'kempo-media:thumbnail_max_dimension')).catch(() => {});
+  /*
+    kempo-files' folders also live on disk, and the disk outlives a database. A run on a fresh in-memory
+    database has no row for the media folder an earlier run left behind, and the migration then refuses
+    to create it ("already exists on disk"). This suite owns that folder, so reset it.
+  */
+  await rm(path.join(process.cwd(), 'files', 'media'), { recursive: true, force: true }).catch(() => {});
   await removeExtensions();
   await db.execute(sql.raw(`ALTER TABLE "kempoMediaAsset" DROP COLUMN IF EXISTS "filename", DROP COLUMN IF EXISTS "path", DROP COLUMN IF EXISTS "thumbnailPath"`)).catch(() => {});
   if(state.site) await rm(state.site, { recursive: true, force: true }).catch(() => {});