kempo 4.7.0 → 4.9.0

package/server/utils/email/readEmailTemplate.js

@@ -0,0 +1,28 @@
+import { readFile } from 'fs/promises';
+import { locateTemplate, sameSource, titleOf } from './emailTemplatePaths.js';
+
+const read = path => readFile(path, 'utf8').catch(() => null);
+
+/*
+  One email template as the site would send it: `source` is the site's own version when it has one and the packaged one
+  otherwise, `defaultSource` is the packaged one (null when there is none), and `overridden` says the site's differs from it.
+  Resolves to [error, { template, owner, name, title, source, defaultSource, overridden }].
+*/
+export default async ({ template } = {}) => {
+  const located = locateTemplate(template);
+  if(!located) return [{ code: 400, msg: 'Invalid email template name' }, null];
+
+  const [site, packaged] = await Promise.all([read(located.sitePath), read(located.defaultPath)]);
+  if(site === null && packaged === null) return [{ code: 404, msg: `Email template not found: ${template}` }, null];
+
+  const source = site ?? packaged;
+  return [null, {
+    template,
+    owner: located.owner,
+    name: located.name,
+    title: titleOf(source),
+    source,
+    defaultSource: packaged,
+    overridden: site !== null && packaged !== null && !sameSource(site, packaged),
+  }];
+};

package/server/utils/email/resetEmailTemplate.js

@@ -0,0 +1,15 @@
+import { readFile, rm } from 'fs/promises';
+import { locateTemplate } from './emailTemplatePaths.js';
+
+/* Removes the site's version of an email template so the packaged one is used again. Resolves to [error, { template }]. */
+export default async ({ template } = {}) => {
+  const located = locateTemplate(template);
+  if(!located) return [{ code: 400, msg: 'Invalid email template name' }, null];
+  if(await readFile(located.defaultPath, 'utf8').catch(() => null) === null) return [{ code: 409, msg: 'There is no packaged version to go back to' }, null];
+  try {
+    await rm(located.sitePath, { force: true });
+    return [null, { template }];
+  } catch {
+    return [{ code: 500, msg: 'The template could not be reset' }, null];
+  }
+};

package/server/utils/email/retryEmail.js

@@ -0,0 +1,21 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, eq, inArray } from 'drizzle-orm';
+import dispatchEmail from './dispatchEmail.js';
+
+/*
+  Tries an email that did not go again, as if it were new: it gets the full number of tries once more. Only a `queued` or `failed`
+  email can be tried again (one that is `sent` or being sent is left alone). Resolves like sendEmail.
+*/
+export default async id => {
+  try {
+    const [row] = await db.update(email)
+      .set({ status: 'queued', attempts: 0, lastError: null, updatedAt: new Date() })
+      .where(and(eq(email.id, String(id ?? '')), inArray(email.status, ['queued', 'failed'])))
+      .returning({ id: email.id });
+    if(!row) return [{ code: 409, msg: 'Only an email that is waiting or failed can be tried again' }, null];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retry the email' }, null];
+  }
+  return dispatchEmail(String(id));
+};

package/server/utils/email/saveEmailTemplate.js

@@ -0,0 +1,38 @@
+import { mkdir, readFile, rm, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+import { locateTemplate } from './emailTemplatePaths.js';
+import renderEmailTemplate from './renderEmailTemplate.js';
+
+const MAX_SOURCE = 100000;
+
+/*
+  The site's own version of an email template, written to `templates/emails/` so it is used from the next email on (the packaged
+  one is never touched). Only a template that exists can be saved, so this cannot make up new names. The new version is rendered
+  once before it is kept, and the old one is put back when it does not render, so a typo cannot stop the site sending that email.
+  Resolves to [error, { template }].
+*/
+export default async ({ template, source } = {}) => {
+  const located = locateTemplate(template);
+  if(!located) return [{ code: 400, msg: 'Invalid email template name' }, null];
+  if(typeof source !== 'string' || !source.trim()) return [{ code: 400, msg: 'The template cannot be empty' }, null];
+  if(source.length > MAX_SOURCE) return [{ code: 400, msg: `The template can be at most ${MAX_SOURCE} characters` }, null];
+  if(source.includes('\u0000')) return [{ code: 400, msg: 'The template cannot contain null characters' }, null];
+
+  const [site, packaged] = await Promise.all([readFile(located.sitePath, 'utf8').catch(() => null), readFile(located.defaultPath, 'utf8').catch(() => null)]);
+  if(site === null && packaged === null) return [{ code: 404, msg: `Email template not found: ${template}` }, null];
+
+  try {
+    await mkdir(dirname(located.sitePath), { recursive: true });
+    await writeFile(located.sitePath, source);
+  } catch {
+    return [{ code: 500, msg: 'The template could not be saved' }, null];
+  }
+
+  const [renderError] = await renderEmailTemplate({ template, data: {} });
+  if(renderError){
+    if(site === null) await rm(located.sitePath, { force: true });
+    else await writeFile(located.sitePath, site);
+    return [{ code: 400, msg: `The template does not render, so it was not saved: ${renderError.msg}` }, null];
+  }
+  return [null, { template }];
+};

package/server/utils/email/sendEmail.js

@@ -1,48 +1,38 @@
-import { Resend } from 'resend';
+import crypto from 'crypto';
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import getSenderFrom from './getSenderFrom.js';
+import dispatchEmail from './dispatchEmail.js';
 
 /*
-  Constructed on first send, not at import. The Resend constructor throws when the key is missing,
-  and this module is reachable from the server SDK, so building it at module scope made an unset
-  RESEND_API_KEY fail every route that transitively imports it rather than just disabling email.
-*/
-let resend = null;
-const client = () => (resend ??= new Resend(process.env.RESEND_API_KEY));
-
-export default async ({ to, subject, html }) => {
-  if(!process.env.RESEND_API_KEY){
-    return [{ code: 500, msg: 'RESEND_API_KEY not configured' }, null];
-  }
+  Asks for an email to be sent. Kempo does not send email itself: this saves the email in the log (the `email` table) and hands it to
+  whichever email extension is installed (kempo-resend, kempo-smtp...) through the `email:send` hook; see dispatchEmail.js.
 
+  `template` is the name of the template the email was made from, if any, and is its type in the log. It resolves to
+  `[null, { id, status: 'sent' }]` when a sender sent it, or `[{ code, msg, emailId }, null]` when none did: 503 when there is no email
+  extension installed, 502 when one tried and failed. Either way the email is in the log, and a failed one is tried again (see the
+  `email_max_retries` setting).
+*/
+export default async ({ to, subject, html, template = null } = {}) => {
   if(!to){
     return [{ code: 400, msg: 'Recipient email is required' }, null];
   }
-  
+
   if(!subject){
     return [{ code: 400, msg: 'Email subject is required' }, null];
   }
-  
+
   if(!html){
     return [{ code: 400, msg: 'Email content is required' }, null];
   }
 
-  const from = process.env.SMTP_FROM || 'onboarding@resend.dev';
-
+  const id = crypto.randomUUID();
+  const now = new Date();
   try {
-    const { data, error } = await client().emails.send({
-      from,
-      to,
-      subject,
-      html,
-    });
-
-    if(error){
-      console.error('Email send error:', error);
-      return [{ code: 500, msg: error.message || 'Failed to send email' }, null];
-    }
-
-    return [null, { success: true, messageId: data.id }];
-  } catch(error){
-    console.error('Email send error:', error);
-    return [{ code: 500, msg: 'Failed to send email' }, null];
+    await db.insert(email).values({ id, type: template || 'other', recipient: String(to), sender: await getSenderFrom(), subject: String(subject), html: String(html), status: 'queued', attempts: 0, createdAt: now, updatedAt: now });
+  } catch(error) {
+    return [{ code: 500, msg: 'The email could not be saved to send' }, null];
   }
+
+  return dispatchEmail(id);
 };

package/server/utils/email/sendEmailFromTemplate.js

@@ -3,7 +3,7 @@ import sendEmail from './sendEmail.js';
 
 /*
   `template` is a plain name for kempo's and the site's templates, or "owner/name" for an extension's;
-  see renderEmailTemplate.js.
+  see renderEmailTemplate.js. It is also the email's type in the log, which the retention settings go by.
 */
 export default async ({ to, subject, template, data = {} }) => {
   if(!to){
@@ -23,5 +23,5 @@ export default async ({ to, subject, template, data = {} }) => {
     return [error, null];
   }
 
-  return await sendEmail({ to, subject, html });
+  return await sendEmail({ to, subject, html, template });
 };

package/server/utils/extensions/checkExtensionUpdate.js

@@ -1,23 +1,11 @@
 import db from '../../db/index.js';
 import { extension } from '../../db/schema.js';
 import { eq } from 'drizzle-orm';
+import { compareVersions, isVersion } from '../updates/helpers.js';
+import fetchManifest from '../updates/fetchManifest.js';
 
-const toRawUrl = (gitUrl, file = 'package.json') => {
-  const match = gitUrl.match(/github\.com\/([^/]+)\/([^/]+)/);
-  if(!match) return null;
-  return `https://raw.githubusercontent.com/${match[1]}/${match[2]}/main/${file}`;
-};
-
-const semverGt = (a, b) => {
-  const parse = v => (v || '0.0.0').replace(/^v/, '').split('.').map(Number);
-  const [aMaj, aMin, aPatch] = parse(a);
-  const [bMaj, bMin, bPatch] = parse(b);
-  if(aMaj !== bMaj) return aMaj > bMaj;
-  if(aMin !== bMin) return aMin > bMin;
-  return aPatch > bPatch;
-};
-
-export default async ({ name }) => {
+/* Whether npm has a newer version of one installed extension than the one recorded for it. */
+export default async ({ name, fetcher }) => {
   if(!name){
     return [{ code: 400, msg: 'Extension name is required' }, null];
   }
@@ -32,25 +20,10 @@ export default async ({ name }) => {
     return [{ code: 500, msg: 'Failed to find extension' }, null];
   }
 
-  const gitUrl = record.kempo?.git;
-  if(!gitUrl){
-    return [null, { hasUpdate: false, reason: 'No git URL configured' }];
-  }
-
-  const rawUrl = toRawUrl(gitUrl);
-  if(!rawUrl){
-    return [null, { hasUpdate: false, reason: 'Unsupported git URL format' }];
-  }
-
-  let remotePkg;
-  try {
-    const res = await fetch(rawUrl);
-    if(!res.ok) return [null, { hasUpdate: false, reason: 'Failed to fetch remote package.json' }];
-    remotePkg = await res.json();
-  } catch(error){
-    return [{ code: 502, msg: 'Failed to reach remote repository' }, null];
-  }
+  const [error, manifest] = await fetchManifest({ name, fetcher });
+  if(error?.code === 404) return [null, { hasUpdate: false, reason: 'This extension is not on npm' }];
+  if(error) return [error, null];
 
-  const hasUpdate = semverGt(remotePkg.version, record.version);
-  return [null, { hasUpdate, currentVersion: record.version, latestVersion: remotePkg.version }];
+  const hasUpdate = isVersion(record.version) && compareVersions(manifest.version, record.version) > 0;
+  return [null, { hasUpdate, currentVersion: record.version, latestVersion: manifest.version }];
 };

package/server/utils/extensions/reconcileExtensions.js

@@ -0,0 +1,90 @@
+import { and, eq } from 'drizzle-orm';
+import { join } from 'path';
+import db from '../../db/index.js';
+import { extension } from '../../db/schema.js';
+import readKempoConfig from './readKempoConfig.js';
+import upgradeExtension from './upgradeExtension.js';
+import { compareVersions, isBreakingBump, isVersion } from '../updates/helpers.js';
+
+/*
+  Brings every installed extension's database in step with the version on disk. Run when the server starts, so it is the one
+  place an update of an extension takes effect, whichever way the new version got there (the Updates screen, a switch of the
+  site's code, npm run by hand, an image that was rebuilt). It is what a deploy script would otherwise have to do.
+
+    on disk is newer than the row    upgradeExtension: its tables, update.js and whatever it newly declares
+    on disk is older than the row    the site went back: the row says so, and no script runs, so going back is safe
+    the same, or not installed       nothing
+
+  The row is claimed first (its version moved to the new one only if it still holds the old), so of several servers starting
+  together exactly one upgrades an extension. A failed upgrade gives the row its old version back, so it is tried again at
+  the next start, and it is reported rather than stopping the server.
+
+  Extensions are taken in dependency order (what each declares in `dependencies`, in the new version's kempo-config.json), so
+  an extension's update script finds the ones it builds on already up to date: kempo-media after kempo-files and kempo-thumbs,
+  kempo-commerce after kempo-products and kempo-payments.
+*/
+let lastRun = { ran: false, upgraded: [], reverted: [], failed: [] };
+
+export const getReconcileResult = () => lastRun;
+
+const isBreaking = (from, to) => isVersion(from) && isVersion(to) && isBreakingBump(from, to);
+
+const newer = (installed, recorded) => (isVersion(installed) && isVersion(recorded) ? compareVersions(installed, recorded) : (installed === recorded ? 0 : 1));
+
+export default async ({ executor = db, root = process.cwd(), upgrade = upgradeExtension } = {}) => {
+  const result = { upgraded: [], reverted: [], failed: [] };
+
+  try {
+    const found = [];
+    for(const row of await executor.select().from(extension)){
+      const extRoot = join(root, 'node_modules', row.name);
+      try {
+        const { pkg, kempo } = await readKempoConfig(extRoot);
+        found.push({ row, extRoot, installed: pkg.version, requires: kempo.dependencies ?? row.kempo?.dependencies ?? [] });
+      } catch {
+        continue;
+      }
+    }
+
+    const ordered = [];
+    const placed = new Set();
+    const place = item => {
+      if(placed.has(item.row.name)) return;
+      placed.add(item.row.name);
+      for(const name of item.requires){
+        const dependency = found.find(other => other.row.name === name);
+        if(dependency) place(dependency);
+      }
+      ordered.push(item);
+    };
+    found.forEach(place);
+
+    for(const { row, extRoot, installed } of ordered){
+      if(!installed || installed === row.version) continue;
+
+      const direction = row.version ? newer(installed, row.version) : 1;
+      if(direction < 0){
+        await executor.update(extension).set({ version: installed, updatedAt: new Date() }).where(eq(extension.name, row.name));
+        result.reverted.push({ name: row.name, from: row.version, to: installed });
+        continue;
+      }
+
+      const claim = and(eq(extension.name, row.name), row.version ? eq(extension.version, row.version) : undefined);
+      const [claimed] = await executor.update(extension).set({ version: installed }).where(claim).returning({ name: extension.name });
+      if(!claimed) continue;
+
+      const [error] = await upgrade({ name: row.name, record: row, extRoot });
+      if(error){
+        await executor.update(extension).set({ version: row.version }).where(eq(extension.name, row.name));
+        result.failed.push({ name: row.name, from: row.version, to: installed, major: isBreaking(row.version, installed), reason: error.msg });
+      } else {
+        result.upgraded.push({ name: row.name, from: row.version, to: installed });
+      }
+    }
+  } catch(error) {
+    return [{ code: 500, msg: `The extensions could not be brought up to date: ${String(error.cause?.message || error.message).slice(0, 300)}` }, result];
+  }
+
+  lastRun = { ran: true, ...result };
+  return [null, result];
+};

package/server/utils/extensions/updateExtension.js

@@ -1,29 +1,29 @@
 import db from '../../db/index.js';
-import { extension, hook, permission, group, groupPermission } from '../../db/schema.js';
-import { eq, and } from 'drizzle-orm';
+import { extension } from '../../db/schema.js';
+import { eq } from 'drizzle-orm';
 import { createRequire } from 'module';
 import { dirname, join } from 'path';
-import { randomUUID } from 'crypto';
 import { execSync } from 'child_process';
-import triggerHook, { clearHandlerCache } from '../hooks/triggerHook.js';
-import createHook from '../hooks/createHook.js';
-import registerDashboardWidget from '../dashboard/registerDashboardWidget.js';
-import unregisterDashboardWidget from '../dashboard/unregisterDashboardWidget.js';
-import registerJobs from '../scheduler/registerJobs.js';
-import setSetting from '../settings/setSetting.js';
-import declaredValue from '../settings/declaredValue.js';
-import createTablesFromSchema from './createTablesFromSchema.js';
 import readKempoConfig from './readKempoConfig.js';
+import upgradeExtension from './upgradeExtension.js';
 import { normalizeAliases } from './aliases.js';
 import { normalizeScopes, scopeNames } from './scopes.js';
 import checkClaims from './checkClaims.js';
 
 const requireFromProject = createRequire(join(process.cwd(), 'package.json'));
 
+/*
+  Installs a newer version of one extension in place, and brings the database in step with it straight away, without a
+  restart (see upgradeExtension). For a site that runs from a Docker volume updates go through the Updates screen instead,
+  which stages them, shows what they change and can go back; this refuses there so it cannot bypass that.
+*/
 export default async ({ name, version = 'latest' }) => {
   if(!name){
     return [{ code: 400, msg: 'Extension name is required' }, null];
   }
+  if(process.env.KEMPO_SITE_ROOT){
+    return [{ code: 409, msg: 'This site updates extensions from the Updates screen' }, null];
+  }
 
   let oldRecord;
   try {
@@ -35,27 +35,18 @@ export default async ({ name, version = 'latest' }) => {
     return [{ code: 500, msg: 'Failed to find extension' }, null];
   }
 
-  const oldKempo = oldRecord.kempo || {};
   const oldVersion = oldRecord.version;
 
-  /*
-    Install updated package
-  */
   try {
     execSync(`npm install ${name}@${version}`, { cwd: process.cwd(), stdio: 'pipe' });
   } catch(error){
     return [{ code: 500, msg: `Failed to update package: ${error.message}` }, null];
   }
 
-  /*
-    What the new version declares comes from its kempo-config.json (package.json's own `kempo` field is
-    only the fallback for an older extension). Reading package.json alone meant that no extension's new
-    permissions, settings, groups, hooks or widgets ever reached the database through this update.
-  */
-  let extRoot, pkg, newKempo;
+  let extRoot, newKempo;
   try {
     extRoot = dirname(requireFromProject.resolve(`${name}/package.json`));
-    ({ pkg, kempo: newKempo } = await readKempoConfig(extRoot));
+    ({ kempo: newKempo } = await readKempoConfig(extRoot));
   } catch {
     return [{ code: 404, msg: `Updated package "${name}" not found` }, null];
   }
@@ -81,135 +72,5 @@ export default async ({ name, version = 'latest' }) => {
     return [{ ...refusal, msg }, null];
   }
 
-  /*
-    Create any new tables from schema
-  */
-  if(newKempo.schema){
-    try {
-      const schemaModule = await import(`${join(extRoot, newKempo.schema)}?t=${Date.now()}`);
-      const [err] = await createTablesFromSchema(schemaModule);
-      if(err) return [err, null];
-    } catch(error){
-      return [{ code: 500, msg: `Failed to load extension schema: ${error.message}` }, null];
-    }
-  }
-
-  /*
-    Run update script with diff context
-  */
-  try {
-    const updateModule = await import(`${join(extRoot, 'update.js')}?t=${Date.now()}`).catch(() => null);
-    if(updateModule?.default){
-      await updateModule.default({ oldVersion, newVersion: pkg.version, oldKempo, newKempo });
-    }
-  } catch(error){
-    return [{ code: 500, msg: `Extension update script failed: ${error.message}` }, null];
-  }
-
-  /*
-    Add new permissions (never delete — user data may depend on them)
-  */
-  const oldPermNames = new Set((oldKempo.permissions || []).map(p => p.name));
-  for(const { name: permName, description } of newKempo.permissions || []){
-    if(!oldPermNames.has(permName)){
-      await db.insert(permission).values({
-        name: permName,
-        description: description || null,
-        owner: name,
-        createdAt: new Date(),
-      }).onConflictDoNothing();
-    }
-  }
-
-  /*
-    Add new settings only (never overwrite — user may have changed the value)
-  */
-  const oldSettingNames = new Set((oldKempo.settings || []).map(s => s.name));
-  for(const { name: settingName, value, type, description } of newKempo.settings || []){
-    if(!oldSettingNames.has(settingName)){
-      await setSetting(name, settingName, declaredValue(value, type), type || null, false, description || null);
-    }
-  }
-
-  /*
-    Add new groups
-  */
-  const oldGroupNames = new Set((oldKempo.groups || []).map(g => g.name));
-  for(const { name: groupName, description, permissions: groupPerms = [] } of newKempo.groups || []){
-    if(!oldGroupNames.has(groupName)){
-      await db.insert(group).values({
-        name: groupName,
-        description: description || null,
-        owner: name,
-        createdAt: new Date(),
-      }).onConflictDoNothing();
-      for(const permName of groupPerms){
-        await db.insert(groupPermission).values({
-          id: randomUUID(),
-          groupName,
-          permissionName: permName,
-          createdAt: new Date(),
-        }).onConflictDoNothing();
-      }
-    }
-  }
-
-  /*
-    Sync hooks: add new, remove deleted
-  */
-  const oldHooks = oldKempo.hooks || {};
-  const newHooks = newKempo.hooks || {};
-  for(const [event, callback] of Object.entries(newHooks)){
-    if(!oldHooks[event]){
-      await createHook({ owner: name, event, callback });
-    }
-  }
-  for(const event of Object.keys(oldHooks)){
-    if(!newHooks[event]){
-      await db.delete(hook).where(and(eq(hook.owner, name), eq(hook.event, event))).catch(() => {});
-    }
-  }
-
-  /*
-    Sync dashboard widgets: register or refresh every declared one, remove those no longer declared
-  */
-  const newWidgetKeys = new Set((newKempo.widgets || []).map(w => w.key));
-  for(const widget of newKempo.widgets || []){
-    const [widgetError] = await registerDashboardWidget({ ...widget, owner: name });
-    if(widgetError){
-      console.warn(`[${name}] dashboard widget "${widget.key}" was not registered: ${widgetError.msg}`);
-    }
-  }
-  for(const { key } of oldKempo.widgets || []){
-    if(!newWidgetKeys.has(key)){
-      await unregisterDashboardWidget({ owner: name, key });
-    }
-  }
-
-  /*
-    Sync scheduled jobs: the schedule becomes exactly what is declared now
-  */
-  if((newKempo.jobs || []).length || (oldKempo.jobs || []).length){
-    const [jobsError] = await registerJobs({ owner: name, jobs: newKempo.jobs || [] });
-    if(jobsError){
-      console.warn(`[${name}] scheduled jobs were not registered: ${jobsError.msg}`);
-    }
-  }
-
-  const now = new Date();
-  try {
-    await db.update(extension).set({
-      version: pkg.version || null,
-      kempo: newKempo,
-      updatedAt: now,
-    }).where(eq(extension.name, name));
-  } catch(error){
-    return [{ code: 500, msg: 'Failed to update extension record' }, null];
-  }
-
-  clearHandlerCache();
-  await triggerHook('extension:updated', { name, oldVersion, newVersion: pkg.version });
-
-  return [null, { name, oldVersion, newVersion: pkg.version }];
+  return upgradeExtension({ name, record: oldRecord, extRoot });
 };
-

package/server/utils/extensions/upgradeExtension.js

@@ -0,0 +1,117 @@
+import db from '../../db/index.js';
+import { extension, hook, permission, group, groupPermission } from '../../db/schema.js';
+import { eq, and } from 'drizzle-orm';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import { randomUUID } from 'crypto';
+import triggerHook, { clearHandlerCache } from '../hooks/triggerHook.js';
+import createHook from '../hooks/createHook.js';
+import registerDashboardWidget from '../dashboard/registerDashboardWidget.js';
+import unregisterDashboardWidget from '../dashboard/unregisterDashboardWidget.js';
+import registerJobs from '../scheduler/registerJobs.js';
+import setSetting from '../settings/setSetting.js';
+import declaredValue from '../settings/declaredValue.js';
+import syncCoreSchema from '../setup/syncCoreSchema.js';
+import readKempoConfig from './readKempoConfig.js';
+import { invalidateScopeCache } from './scopeCache.js';
+
+/*
+  Brings the database in step with a newer version of an extension that is already on disk: its tables (additions only: new
+  tables, columns and indexes), its own `update.js` (given the old and new version and what each declared), and whatever the
+  new version declares that the old one did not (permissions, settings, groups, hooks, dashboard widgets and scheduled jobs).
+  It only adds: a permission, setting or group an extension no longer declares stays, because data may depend on it, and a
+  setting the owner changed keeps their value. Hooks, widgets and jobs follow what is declared now.
+
+  `record` is the extension's row as it was before. Resolves to [error, { name, oldVersion, newVersion }]. Run by the startup
+  step (reconcileExtensions) and by updateExtension, never on a version that is older than the row's.
+*/
+export default async ({ name, record, extRoot = join(process.cwd(), 'node_modules', name) }) => {
+  const oldKempo = record.kempo || {};
+  const oldVersion = record.version;
+
+  let pkg, newKempo;
+  try {
+    ({ pkg, kempo: newKempo } = await readKempoConfig(extRoot));
+  } catch {
+    return [{ code: 404, msg: `Package "${name}" is not installed` }, null];
+  }
+
+  if(newKempo.schema){
+    try {
+      const schemaModule = await import(`${pathToFileURL(join(extRoot, newKempo.schema)).href}?t=${Date.now()}`);
+      const [schemaError, synced] = await syncCoreSchema({ schema: schemaModule });
+      if(schemaError) return [schemaError, null];
+      for(const { change, reason } of synced.failed) console.warn(`[${name}] database change not applied: ${change}: ${reason}`);
+    } catch(error) {
+      return [{ code: 500, msg: `Failed to load extension schema: ${error.message}` }, null];
+    }
+  }
+
+  try {
+    const updateModule = await import(`${pathToFileURL(join(extRoot, 'update.js')).href}?t=${Date.now()}`).catch(() => null);
+    if(updateModule?.default){
+      await updateModule.default({ oldVersion, newVersion: pkg.version, oldKempo, newKempo });
+    }
+  } catch(error) {
+    return [{ code: 500, msg: `Extension update script failed: ${error.message}` }, null];
+  }
+
+  const oldPermNames = new Set((oldKempo.permissions || []).map(p => p.name));
+  for(const { name: permName, description } of newKempo.permissions || []){
+    if(!oldPermNames.has(permName)){
+      await db.insert(permission).values({ name: permName, description: description || null, owner: name, createdAt: new Date() }).onConflictDoNothing();
+    }
+  }
+
+  const oldSettingNames = new Set((oldKempo.settings || []).map(s => s.name));
+  for(const { name: settingName, value, type, description } of newKempo.settings || []){
+    if(!oldSettingNames.has(settingName)){
+      await setSetting(name, settingName, declaredValue(value, type), type || null, false, description || null);
+    }
+  }
+
+  const oldGroupNames = new Set((oldKempo.groups || []).map(g => g.name));
+  for(const { name: groupName, description, permissions: groupPerms = [] } of newKempo.groups || []){
+    if(!oldGroupNames.has(groupName)){
+      await db.insert(group).values({ name: groupName, description: description || null, owner: name, createdAt: new Date() }).onConflictDoNothing();
+      for(const permName of groupPerms){
+        await db.insert(groupPermission).values({ id: randomUUID(), groupName, permissionName: permName, createdAt: new Date() }).onConflictDoNothing();
+      }
+    }
+  }
+
+  const oldHooks = oldKempo.hooks || {};
+  const newHooks = newKempo.hooks || {};
+  for(const [event, callback] of Object.entries(newHooks)){
+    if(!oldHooks[event]) await createHook({ owner: name, event, callback });
+  }
+  for(const event of Object.keys(oldHooks)){
+    if(!newHooks[event]) await db.delete(hook).where(and(eq(hook.owner, name), eq(hook.event, event))).catch(() => {});
+  }
+
+  const newWidgetKeys = new Set((newKempo.widgets || []).map(w => w.key));
+  for(const widget of newKempo.widgets || []){
+    const [widgetError] = await registerDashboardWidget({ ...widget, owner: name });
+    if(widgetError) console.warn(`[${name}] dashboard widget "${widget.key}" was not registered: ${widgetError.msg}`);
+  }
+  for(const { key } of oldKempo.widgets || []){
+    if(!newWidgetKeys.has(key)) await unregisterDashboardWidget({ owner: name, key });
+  }
+
+  if((newKempo.jobs || []).length || (oldKempo.jobs || []).length){
+    const [jobsError] = await registerJobs({ owner: name, jobs: newKempo.jobs || [] });
+    if(jobsError) console.warn(`[${name}] scheduled jobs were not registered: ${jobsError.msg}`);
+  }
+
+  try {
+    await db.update(extension).set({ version: pkg.version || null, kempo: newKempo, updatedAt: new Date() }).where(eq(extension.name, name));
+  } catch {
+    return [{ code: 500, msg: 'Failed to update extension record' }, null];
+  }
+
+  clearHandlerCache();
+  invalidateScopeCache();
+  await triggerHook('extension:updated', { name, oldVersion, newVersion: pkg.version });
+
+  return [null, { name, oldVersion, newVersion: pkg.version }];
+};