kempo-media 0.2.3

package/.env.example

@@ -0,0 +1 @@
+DATABASE_URL=postgresql://kempo:kempo_media_test_password@localhost:5435/kempo_media_test

package/.gitattributes

@@ -0,0 +1,5 @@
+# Normalise every text file to LF in the repository, and check it out with the
+# platform's native endings. Without this, a Windows build writes CRLF into files that
+# checkout wrote as LF, so git reports them as modified even though the content is
+# identical — `git diff` shows nothing while `git status` shows a change.
+* text=auto

package/.github/workflows/publish.yml

@@ -0,0 +1,85 @@
+name: Publish to npmjs
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+    inputs:
+      version-type:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+        default: patch
+
+jobs:
+  publish:
+    # [skip publish] lands a commit on master without releasing while still running the tests,
+    # which a shared [skip ci] marker cannot do since that skips the test workflow too.
+    # A manual run always publishes.
+    if: "github.event_name == 'workflow_dispatch' || !(contains(github.event.head_commit.message, '[skip ci]') || contains(github.event.head_commit.message, '[skip publish]'))"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - run: npm ci
+
+      - name: Build project and documentation
+        run: |
+          npm run build
+
+      # kempo/kempo-ui/kempo-server are peer dependencies and are not installed by npm ci above.
+      # The published release is the right one to test against: it is what a site installing this
+      # extension will actually pair it with.
+      - name: Install the host for the test gate
+        run: npm install --no-save kempo@latest kempo-ui@latest kempo-server@latest
+
+      - name: Run Unit Tests
+        run: npm test
+
+      - name: Set version type
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            echo "type=${{ inputs.version-type }}" >> $GITHUB_OUTPUT
+          else
+            echo "type=patch" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Bump ${{ steps.version.outputs.type }} version
+        run: |
+          git config --global user.name "github-actions"
+          git config --global user.email "github-actions@github.com"
+          npm version ${{ steps.version.outputs.type }} --no-git-tag-version
+          git add -A || true
+          git commit -m "ci: bump ${{ steps.version.outputs.type }} version [skip ci]" || echo "No changes to commit"
+          # Must be the branch that triggered this run — hardcoding a branch name silently drifts
+          # git and npm apart the day the default branch changes.
+          git push origin HEAD:${{ github.ref_name }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup .npmrc for OIDC
+        run: |
+          cat << EOF > ~/.npmrc
+          //registry.npmjs.org/:_authToken=\${NPM_TOKEN}
+          registry=https://registry.npmjs.org/
+          always-auth=true
+          EOF
+
+      - run: npm publish --access public
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/test.yml

@@ -0,0 +1,123 @@
+name: Run Unit Tests
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - 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:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    runs-on: ubuntu-latest
+    services:
+      # The API-contract and data-layer suites need a real database; they skip themselves when
+      # none is reachable, so this is what makes them actually run rather than silently pass.
+      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
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - run: npm ci
+
+      # kempo/kempo-ui/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-ui@latest kempo-server@latest
+
+      - name: Apply database schema
+        run: npx drizzle-kit push --force
+
+      - name: Run Unit Tests
+        run: npm test
+
+  # 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
+  # surfaces that before a release, and it is advisory rather than blocking.
+  siblings:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    services:
+      # Without this the database-backed suites skip themselves, which reads as a pass.
+      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:
+          path: kempo-media
+
+      - uses: actions/checkout@v4
+        with:
+          repository: dustinpoissant/kempo
+          path: kempo
+
+      - uses: actions/checkout@v4
+        with:
+          repository: dustinpoissant/kempo-server
+          path: kempo-server
+
+      # kempo's own link:local script links both kempo-server and kempo-ui as siblings, so this
+      # checkout needs to exist even though kempo-media itself doesn't import kempo-ui server-side.
+      - uses: actions/checkout@v4
+        with:
+          repository: dustinpoissant/kempo-ui
+          path: kempo-ui
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Install host
+        run: npm ci && npm run link:local
+        working-directory: kempo
+
+      - run: npm ci
+        working-directory: kempo-media
+
+      - name: Link sibling checkouts
+        run: npm run link:local
+        working-directory: kempo-media
+
+      - name: Apply database schema
+        run: npx drizzle-kit push --force
+        working-directory: kempo-media
+
+      - name: Run Unit Tests
+        run: npm test
+        working-directory: kempo-media

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+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).
+
+## [0.2.0] - 2026-08-13
+### Added
+ - **Uploads.** `POST /kempo-media/api/media` accepts a `multipart/form-data` upload, validates its type, stores it under a generated name in the site's own `public/media/uploads/`, and records it. The multipart parser is written here rather than pulled in: the usual libraries stream a body that is still arriving, and kempo-server has already buffered the whole thing by the time a route runs. It works entirely on Buffers, so file content is never decoded — decoding it as UTF-8 is exactly the corruption kempo-server 3.2.0 fixed.
+ - **Thumbnails for images**, via `sharp`, imported lazily so a failed native build degrades to "no preview" rather than an extension that will not load. Other kinds get a type icon.
+ - **Browse, rename, edit alt text and delete**, over `GET`/`PATCH`/`DELETE` on the same route, each behind its own permission. Deleting removes the files as well as the row, and tolerates a file that has already gone from disk rather than leaving an undeletable entry.
+ - **The media library admin screen** at *Media*: a thumbnail grid with search, type filtering, drag-and-drop upload with per-file progress, and delete. Uploads run one at a time — bodies are buffered in memory server-side, so sending ten large files at once is the surest way to exhaust it.
+ - **An editor picker.** `admin/asset-picker.global.html` installs `window.kempo.openAssetPicker`, so kempo-ui's image control shows a **Browse…** button that opens the same library. Nothing in kempo core needed changing: it already scans every enabled extension's `admin/` directory for `*.global.html` on each render.
+ - **A parse check over every browser module.** Those files import absolute `/kempo-ui/…` URLs, so nothing else in the node suite loads them, and a backtick inside a comment in an `html``/`css`` literal terminates the literal and stops the module parsing — the element then silently never upgrades. `node --check` catches it without a browser.
+
+### Security
+ - **SVG is not an accepted upload type.** kempo-server serves it as inline unsanitised markup on the site's own origin, making an uploaded SVG with a `<script>` stored XSS against the admin who opens it.
+ - **Supplied filenames never reach the filesystem.** Names on disk are generated; the original is kept for display only, which makes `../../../../etc/passwd.png` a harmless label rather than a traversal.
+
+### Changed
+ - Requires `kempo-server` >= 3.2.0 and, for the editor picker only, `kempo-ui` >= 0.4.43.
+
+## [0.1.0] - 2026-08-12
+### Added
+ - Initial extension scaffold: `kempo-config.json` (permissions, settings, groups), the `kempoMediaAsset` table, `install.js`/`update.js`, admin nav registration, and the baseline test suite (module graph, package invariants, permission-name consistency).

package/README.md

@@ -0,0 +1,114 @@
+# kempo-media
+
+Media library extension for [kempo](https://github.com/dustinpoissant/kempo) — upload and manage images, video, audio, 3D models and archives, with a picker wired into the editor's image control.
+
+## What it does
+
+- **A media library in the admin**, at *Media* in the sidebar: a grid of thumbnails with search, filtering by type, drag-and-drop upload with per-file progress, and delete.
+- **A picker in the editor.** kempo-ui's image control grows a **Browse…** button that opens the library, so an author inserts an image by looking at it instead of remembering its URL.
+- **Thumbnails for images**, generated on upload. Other kinds show a type icon.
+- **Range-request support for free.** Uploads are stored in your site's own `public/`, so kempo-server serves them directly and video and audio seek properly.
+
+## Requirements
+
+| Package | Version | Why |
+|---|---|---|
+| `kempo` | >= 4.2.26 | Extension host |
+| `kempo-server` | >= 3.2.0 | First release with binary-safe request bodies. On anything earlier, uploaded files arrive corrupted. |
+| `kempo-ui` | >= 0.4.43 | First release with the `window.kempo.openAssetPicker` hook the editor picker uses. The library itself works without it. |
+
+## Install
+
+```
+npm install kempo-media
+```
+
+Then install it from kempo's admin under **Extensions**. On install it creates `public/media/uploads/` and `public/media/thumbnails/` in your site.
+
+## Permissions
+
+| Name | Grants |
+|---|---|
+| `media:browse` | List and view library assets |
+| `media:upload` | Upload new assets |
+| `media:update` | Edit alt text and rename |
+| `media:delete` | Delete assets |
+
+A `kempo-media:editor` group is created granting browse, upload and update — but not delete.
+
+## Settings
+
+| Name | Default | Description |
+|---|---|---|
+| `max_upload_size_mb` | `250` | Largest single file accepted |
+| `thumbnail_max_dimension` | `480` | Longest edge of generated thumbnails, in pixels |
+
+`max_upload_size_mb` sits **below** kempo-server's own `maxBodySize` (500 MB by default), which is the real ceiling. Raising this setting above that has no effect; the request is rejected before this extension sees it.
+
+## Accepted file types
+
+| Kind | Extensions |
+|---|---|
+| Image | `png` `jpg` `jpeg` `gif` `webp` `avif` |
+| Video | `mp4` `m4v` `webm` `ogv` |
+| Audio | `mp3` `ogg` `wav` |
+| 3D model | `glb` `gltf` `obj` `fbx` |
+| Archive | `zip` |
+
+**SVG is deliberately not accepted.** kempo-server serves SVG as inline, unsanitised markup on your site's own origin, so an uploaded SVG carrying a `<script>` would be stored XSS against the admin who opens it. Supporting it needs a sanitiser first, not just an entry in the list.
+
+## Using assets from your own code
+
+Uploaded files are served from your site root, so an asset's `path` is its URL:
+
+```js
+import { getMediaAssets } from 'kempo-media/sdk';
+
+const [error, data] = await getMediaAssets({ kind: 'image', limit: 10 });
+// data.assets[0].path === 'media/uploads/a1b2c3d4e5f60718.png'  ->  /media/uploads/...
+```
+
+The same functions are available in the browser from `/kempo-media/sdk.js`, plus `uploadMedia(file, { alt }, onProgress)`.
+
+## Providing your own picker
+
+The editor hook is just a global. Any extension can install one, and the last one to load wins:
+
+```js
+window.kempo.openAssetPicker = async ({ alt }) => ({ url: '/some/image.png', alt });
+```
+
+Resolve `null` to insert nothing. See kempo-ui's markdown-editor documentation for the full contract.
+
+## Local development
+
+```
+npm run link:local   # links sibling ../kempo and ../kempo-ui checkouts
+npm test
+```
+
+Note that `npm install <anything>` in a consuming project drops packages linked with `--no-save`, so re-run `link:local` after one.
+
+`npm test` runs both node and headless-browser tests (Puppeteer downloads its own Chromium on `npm install`, nothing extra to set up). The browser suites cover `admin/components/MediaLibrary.js` — a real Lit component that imports `/kempo-ui/...` and `/kempo-media/sdk.js` by absolute URL, the same way it does on a live site. `tests/browser-fixtures.node-test.js` runs first (node tests always finish before any browser test starts) and links `kempo-ui` and `kempo-media` directories at the repo root so those imports resolve against the test server; `kempo-media` there points at a fake `sdk.js` (`tests/fixtures/kempo-media-sdk-mock/`) that each test controls via `window.__mediaSdkMock`, not the real one, since these tests don't boot a server.
+
+### Running the database-backed tests
+
+Two suites (`tests/media-api-contract.node-test.js`, `tests/media-data-layer.node-test.js`) drive this extension against a real Postgres — one installs it and hits its actual HTTP routes, the other exercises the CRUD layer directly. Both skip themselves with a clear message when no database is reachable, so `npm test` is safe to run without one. To actually run them:
+
+```
+docker compose up -d                                   # starts kempo-media-test-db on localhost:5435
+export DATABASE_URL=$(grep DATABASE_URL .env.example | cut -d= -f2-)
+npx drizzle-kit push --force                            # creates kempo's core tables + kempoMediaAsset
+npm test
+```
+
+`DATABASE_URL` needs to be a real environment variable for both `drizzle-kit` and `npm test` — this repo has no dotenv step of its own to load a `.env` file, so `.env.example` is a copy-paste reference, not something read automatically.
+
+`drizzle.config.js` here exists only for this — the table itself is created for real via `createTablesFromSchema` at install time, the same as it would be on a live site.
+
+## Known limits
+
+- **Uploads are buffered in memory, not streamed to disk.** kempo-server reads the whole request body before a route runs, so a very large upload is bounded by available RAM rather than disk. `maxBodySize` is the ceiling.
+- **Thumbnails are images only.** No video frame extraction or waveforms — that needs ffmpeg and a job queue, neither of which exists here.
+- **`sharp` is a native module.** It is the one dependency that can fail to install on an unusual host. It is imported lazily, so if it is missing you get uploads without thumbnails rather than a broken extension.
+- **No usage tracking.** Deleting an asset does not check whether a page links to it.

package/admin/asset-picker.global.html

@@ -0,0 +1,63 @@
+<content id="kempo-media-asset-picker" name="Media asset picker" owner="kempo-media" enabled="true" locked="true" location="scripts" priority="0">
+<script type="module">
+  /*
+    Installs the picker kempo-ui's image control looks for. kempo core scans every enabled
+    extension's admin/ directory for *.global.html on each admin render, so this lands in the
+    scripts location of every admin page with no changes to core and no registration step.
+
+    The hook is read when the control's dropdown opens rather than at page load, so setting it here
+    is early enough regardless of which loads first.
+  */
+  import Dialog from '/kempo-ui/components/Dialog.js';
+  import '/admin/extension/kempo-media/components/MediaLibrary.js';
+
+  window.kempo = window.kempo || {};
+
+  window.kempo.openAssetPicker = ({ alt = '' } = {}) => new Promise(resolve => {
+    const library = document.createElement('kempo-media-library');
+    library.selectable = true;
+    library.canUpload = true;   // uploading and then immediately using it is the common flow
+    library.kind = 'image';     // the caller is the image control; other kinds are a click away
+    library.style.minWidth = 'min(48rem, 80vw)';
+
+    /*
+      resolve() is idempotent by contract but the paths overlap — a double-click confirms and then
+      the dialog closes, firing closeCallback too. Guarding here keeps the first answer.
+    */
+    let settled = false;
+    const settle = value => {
+      if(settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    const chosen = asset => ({
+      url: `/${asset.path}`,
+      // The asset's own alt text describes the file; fall back to whatever was already typed
+      alt: asset.altText || alt
+    });
+
+    library.addEventListener('asset-confirmed', e => {
+      settle(chosen(e.detail.asset));
+      dialog?.close();
+    });
+
+    const dialog = Dialog.create(library, {
+      title: 'Select media',
+      confirmText: 'Insert',
+      cancelText: 'Cancel',
+      confirmAction: event => {
+        const asset = library.selectedAsset;
+        if(!asset){
+          // Nothing picked yet — keep the dialog up rather than silently inserting nothing
+          event.keepDialogOpen = true;
+          return;
+        }
+        settle(chosen(asset));
+      },
+      // Fires on every dismissal route: cancel, the close button, the overlay, and Escape
+      closeCallback: () => settle(null)
+    });
+  });
+</script>
+</content>