kempo 4.8.0 → 4.9.1

package/middleware/kempo.js

@@ -13,9 +13,16 @@ import triggerHook from '../server/utils/hooks/triggerHook.js';
 import { ADMIN_GLOBALS_DIR } from '../server/utils/admin-global-content/helpers.js';
 import { startScheduler } from '../server/utils/scheduler/scheduler.js';
 import { ensureEncryptionKey } from '../server/utils/settings/ensureEncryptionKey.js';
+import syncCoreSchema from '../server/utils/setup/syncCoreSchema.js';
+import runUpgrades from '../server/utils/setup/runUpgrades.js';
+import seedIfNew from '../server/utils/setup/seedIfNew.js';
+import reconcileExtensions from '../server/utils/extensions/reconcileExtensions.js';
+import { flagFailed, markHealthy } from '../server/utils/updates/siteLayout.js';
+import notifySchemaAttention from '../server/utils/updates/notifySchemaAttention.js';
 import { ensureSystemSettings } from '../server/utils/settings/systemSettings.js';
 import { ensureSystemPermissions } from '../server/utils/setup/systemPermissions.js';
 import registerJobs from '../server/utils/scheduler/registerJobs.js';
+import '../server/utils/updates/runtime.js';
 import { resolveAlias } from '../server/utils/extensions/aliases.js';
 import { normalizeScopes } from '../server/utils/extensions/scopes.js';
 
@@ -187,6 +194,11 @@ const serveDir = async (dirPath, method, request, response, resolveDir, rootDir,
 export default config => {
   startScheduler();
 
+  /* A site that runs from a Docker volume has just switched to new code: once it has stayed up a minute the switch is final. */
+  if(process.env.KEMPO_SITE_ROOT && process.env.KEMPO_DB !== 'pglite'){
+    setTimeout(() => markHealthy(process.env.KEMPO_SITE_ROOT), 60000).unref();
+  }
+
   /*
     The key that encrypts stored credentials exists before any request needs it, generated into .env the
     first time when the site has none. Opt out with `autoEncryptionKey: false` in the server config or
@@ -198,17 +210,55 @@ export default config => {
       if(error) console.error(`[kempo] ${error.msg}`);
     });
   /*
-    What kempo added in a later version appears on an older site at start: its settings (so they show on the settings screen and can be
-    edited), its permissions, and its own scheduled job (the email retries and cleanup). Only what is missing is added, and never in
+    What kempo added in a later version appears on an older site at start: its tables and columns (additive only, see syncCoreSchema), its settings (so they show on the settings screen and can be
+    edited), its permissions, and its own scheduled jobs (the email retries and cleanup, and the check for a newer kempo). Only what is missing is added, and never in
     the in-memory test database (nothing is set up there yet).
   */
   const systemSettingsReady = process.env.KEMPO_DB === 'pglite'
     ? Promise.resolve()
     : (async () => {
       for(const [step, run] of [
+        ['schema', async () => {
+          const [error, result] = await syncCoreSchema();
+          if(result?.applied.length) console.log(`[kempo] Database brought up to date: ${result.applied.join('; ')}`);
+          for(const { change, reason } of result?.failed ?? []) console.error(`[kempo] Database change failed: ${change}: ${reason}`);
+          return [error];
+        }],
+        ['seed', async () => {
+          const [error, result] = await seedIfNew();
+          if(result?.seeded) console.log('[kempo] New database: its groups, permissions and settings were set up. Open /setup to create the first administrator.');
+          return [error];
+        }],
+        ['upgrades', async () => {
+          const [error, result] = await runUpgrades();
+          if(result?.ran.length) console.log(`[kempo] Data migrations run: ${result.ran.join(', ')}`);
+          if(error){
+            console.error(`[kempo] ${error.msg}`);
+            if(error.breaking && process.env.KEMPO_SITE_ROOT){
+              flagFailed({ siteRoot: process.env.KEMPO_SITE_ROOT, reason: error.msg });
+              process.exit(1);
+            }
+          }
+          return [null];
+        }],
         ['settings', ensureSystemSettings],
         ['permissions', ensureSystemPermissions],
-        ['jobs', () => registerJobs({ owner: 'kempo', jobs: [{ name: 'email-maintenance', every: '1m', callback: './server/utils/email/maintainEmails.js' }] })],
+        ['extensions', async () => {
+          const [error, result] = await reconcileExtensions();
+          for(const { name, from, to } of result?.upgraded ?? []) console.log(`[kempo] Extension ${name} brought up to date: ${from} -> ${to}`);
+          for(const { name, from, to } of result?.reverted ?? []) console.log(`[kempo] Extension ${name} is back on ${to} (was ${from})`);
+          for(const { name, reason } of result?.failed ?? []) console.error(`[kempo] Extension ${name} could not be brought up to date: ${reason}`);
+          if(result?.failed.some(item => item.major) && process.env.KEMPO_SITE_ROOT){
+            flagFailed({ siteRoot: process.env.KEMPO_SITE_ROOT, reason: result.failed.filter(item => item.major).map(item => `${item.name}: ${item.reason}`).join('; ') });
+            process.exit(1);
+          }
+          return [error];
+        }],
+        ['schema notice', notifySchemaAttention],
+        ['jobs', () => registerJobs({ owner: 'kempo', jobs: [
+          { name: 'email-maintenance', every: '1m', callback: './server/utils/email/maintainEmails.js' },
+          { name: 'update-check', every: '12h', callback: './server/utils/updates/runUpdateCheck.js' },
+        ] })],
       ]){
         const [error] = await run();
         if(error) console.error(`[kempo] System ${step}: ${error.msg}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo",
-  "version": "4.8.0",
+  "version": "4.9.1",
   "type": "module",
   "description": "A fullstack CMS framework for creating websites with user authentication",
   "scripts": {
@@ -33,6 +33,8 @@
     "server/utils",
     "server/db/index.js",
     "server/db/schema.js",
+    "server/db/upgrades",
+    "docker",
     "server/sdk.js",
     "middleware/kempo.js",
     "app-templates",

package/server/db/schema.js

@@ -115,6 +115,18 @@ export const extension = pgTable('extension', {
   updatedAt: timestamp('updatedAt').notNull(),
 });
 
+/*
+  Which of kempo's own data migrations (server/db/upgrades/*.js) have run on this database. The additive changes to its
+  tables need no record, they are found by comparing; a migration that restructures data runs once and is recorded here.
+  The row with id 'baseline' marks the database as already holding what the shipped migrations produce.
+*/
+export const upgrade = pgTable('upgrade', {
+  id: text('id').primaryKey(),
+  description: text('description'),
+  breaking: boolean('breaking').notNull().default(false),
+  appliedAt: timestamp('appliedAt').notNull().defaultNow(),
+});
+
 /*
   Scheduled jobs: recurring work an extension declares in its kempo-config.json `jobs`. A row per job
   is the schedule and the lease: `nextRunAt` is when it is next due and `lockedUntil` is held while a

package/server/db/upgrades/README.md

@@ -0,0 +1,20 @@
+# Data migrations
+
+Additive changes to kempo's tables (new tables, columns, indexes) need nothing here: they are applied when the server starts.
+A change that restructures or moves data goes in a file in this folder, named so that they sort in the order they must run:
+
+    4.9.0-split-user-name.js
+
+```js
+export const meta = { description: 'Splits user.name into first and last', breaking: true };
+
+export const up = async ({ db, sql }) => {
+  await db.execute(sql`...`);
+};
+```
+
+- It runs once, inside a transaction, when the first server of the new version starts, and is recorded in the `upgrade` table.
+- `breaking: true` is for anything the previous version cannot run against (data moved or removed). The Updates screen warns
+  before such an update, kempo backs the database up first, and a failure puts the previous version and that backup back.
+- Add one only in a release whose version is higher than the first one that has this folder: a site's `upgrade` table starts with
+  every file that was here when it first started recorded as already run.

package/server/sdk.js

@@ -221,6 +221,9 @@ export { default as installExtension } from './utils/extensions/installExtension
 export { default as listExtensions } from './utils/extensions/listExtensions.js';
 export { default as uninstallExtension } from './utils/extensions/uninstallExtension.js';
 export { default as updateExtension } from './utils/extensions/updateExtension.js';
+export { default as upgradeExtension } from './utils/extensions/upgradeExtension.js';
+export { default as reconcileExtensions } from './utils/extensions/reconcileExtensions.js';
+export { default as writeSiteFile } from './utils/extensions/writeSiteFile.js';
 
 /*
   Notifications

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 }];
+};