kempo 4.8.0 → 4.9.1

package/server/utils/extensions/writeSiteFile.js

@@ -0,0 +1,66 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, normalize, sep } from 'path';
+
+/*
+  For an extension that has to put a file into the site (a generated template, a starter page): writes it the way kempo's own
+  starter files are handled, so an update of the extension never overwrites what the owner changed.
+
+    not there, never written by this extension     written
+    not there, but this extension wrote it before  the owner deleted it, so it stays deleted
+    identical to what is being written             nothing to do
+    still exactly what this extension last wrote   never edited, so replaced
+    anything else                                  edited by the owner (or anyone), so kept
+
+  The extension's fingerprints are in .kempo/shipped/<owner>.json. `path` is relative to the site and must be inside public/
+  or templates/. Most extensions need none of this, because their own public/ is served from the package; this is for the
+  few that generate something into the site. Resolves to [error, { status }] where status is "written", "current", "kept"
+  or "deleted".
+*/
+const hashOf = content => createHash('sha256').update(content).digest('hex');
+
+export default ({ owner, path, content, cwd = process.cwd() } = {}) => {
+  if(typeof owner !== 'string' || !/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(owner)){
+    return [{ code: 400, msg: 'owner must be the extension name' }, null];
+  }
+  const relative = typeof path === 'string' ? normalize(path).split(sep).join('/') : '';
+  if(!relative || relative.startsWith('..') || relative.startsWith('/') || !/^(public|templates)\//.test(relative)){
+    return [{ code: 400, msg: 'path must be a file inside public/ or templates/' }, null];
+  }
+  if(typeof content !== 'string' && !Buffer.isBuffer(content)){
+    return [{ code: 400, msg: 'content must be text or a buffer' }, null];
+  }
+
+  const recordFile = join(cwd, '.kempo', 'shipped', `${owner.replace('/', '__')}.json`);
+  let files = {};
+  try {
+    files = JSON.parse(readFileSync(recordFile, 'utf8')).files ?? {};
+  } catch {
+    files = {};
+  }
+  const save = () => {
+    mkdirSync(dirname(recordFile), { recursive: true });
+    writeFileSync(recordFile, JSON.stringify({ files }, null, 2));
+  };
+
+  const target = join(cwd, relative);
+  const wanted = hashOf(content);
+
+  if(!existsSync(target)){
+    if(files[relative]) return [null, { status: 'deleted' }];
+  } else {
+    const here = hashOf(readFileSync(target));
+    if(here === wanted){
+      files[relative] = wanted;
+      save();
+      return [null, { status: 'current' }];
+    }
+    if(files[relative] !== here) return [null, { status: 'kept' }];
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+  files[relative] = wanted;
+  save();
+  return [null, { status: 'written' }];
+};

package/server/utils/settings/systemSettings.js

@@ -20,6 +20,7 @@ export const SYSTEM_SETTINGS = [
   { owner: 'system', name: 'email_retention_days', value: 30, type: 'number', isPublic: false, description: 'Days to keep the log of sent emails before it is deleted (0 keeps it forever)' },
   { owner: 'system', name: 'email_retention_by_type', value: {}, type: 'json', isPublic: false, description: 'Days to keep a particular kind of email, instead of the number above, as { "verify-email": 7, "kempo-commerce/order-processing": 365 } (0 keeps that kind forever)' },
   { owner: 'system', name: 'email_from', value: '', type: 'string', isPublic: false, description: 'The address emails are sent from, as name@example.com or Shop Name <name@example.com>. It must be on a domain verified with the email provider. Empty uses EMAIL_FROM from the server environment' },
+  { owner: 'system', name: 'update_check_enabled', value: true, type: 'boolean', isPublic: false, description: 'Check npm every 12 hours for a newer kempo and tell the people who can install it' },
 ];
 
 /* Resolves to [error, { added: [names] }]. */

package/server/utils/setup/runUpgrades.js

@@ -0,0 +1,70 @@
+import { existsSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { sql } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { upgrade } from '../../db/schema.js';
+
+/*
+  Kempo's own data migrations: the files in server/db/upgrades, which restructure or move data that the additive sync of
+  the tables (syncCoreSchema) cannot. See that folder's README for how to write one.
+
+  They run in file-name order, each once, in a transaction, when the server starts and after the tables are in step. A
+  database that has never had the `upgrade` table is taken to already hold what the shipped migrations make (a new site,
+  or a site on its first version with this): they are recorded as run without being run, under a row called 'baseline'.
+*/
+export const DEFAULT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'db', 'upgrades');
+
+const filesIn = dir => (existsSync(dir) ? readdirSync(dir).filter(name => name.endsWith('.js')).sort() : []);
+
+const load = (dir, file) => import(`${pathToFileURL(join(dir, file)).href}?t=${Date.now()}`);
+
+const appliedIds = async executor => new Set((await executor.select({ id: upgrade.id }).from(upgrade)).map(row => row.id));
+
+/*
+  What would run, in order, as [{ id, description, breaking }]. `dir` is another version's folder, to look ahead at an
+  update before it is switched to. Nothing is run or recorded.
+*/
+export const pendingUpgrades = async ({ dir = DEFAULT_DIR, executor = db } = {}) => {
+  const applied = await appliedIds(executor);
+  if(!applied.has('baseline')) return [];
+  const pending = [];
+  for(const file of filesIn(dir).filter(name => !applied.has(name))){
+    const { meta = {} } = await load(dir, file);
+    pending.push({ id: file, description: meta.description ?? '', breaking: Boolean(meta.breaking) });
+  }
+  return pending;
+};
+
+/*
+  Resolves to [error, { ran }]. An error is the first migration that failed, with `breaking` saying whether it was one the
+  previous version cannot run without; nothing after it runs, and what it did is rolled back.
+*/
+export default async ({ dir = DEFAULT_DIR, executor = db } = {}) => {
+  try {
+    const applied = await appliedIds(executor);
+    if(!applied.has('baseline')){
+      await executor.transaction(async tx => {
+        for(const id of [...filesIn(dir), 'baseline']) await tx.insert(upgrade).values({ id, description: id === 'baseline' ? 'Existing migrations were already part of this database' : 'Part of the baseline' }).onConflictDoNothing();
+      });
+      return [null, { ran: [] }];
+    }
+
+    const ran = [];
+    for(const file of filesIn(dir).filter(name => !applied.has(name))){
+      const { meta = {}, up } = await load(dir, file);
+      try {
+        await executor.transaction(async tx => {
+          await up({ db: tx, sql });
+          await tx.insert(upgrade).values({ id: file, description: meta.description ?? null, breaking: Boolean(meta.breaking) });
+        });
+        ran.push(file);
+      } catch(error) {
+        return [{ code: 500, msg: `The data migration ${file} failed: ${String(error.cause?.message || error.message).slice(0, 300)}`, breaking: Boolean(meta.breaking), id: file }, { ran }];
+      }
+    }
+    return [null, { ran }];
+  } catch(error) {
+    return [{ code: 500, msg: `The data migrations could not be checked: ${String(error.cause?.message || error.message).slice(0, 300)}`, breaking: false }, null];
+  }
+};

package/server/utils/setup/seedDatabase.js

@@ -22,7 +22,7 @@ const DEFAULT_GROUPS = {
       'system:fragments:read', 'system:fragments:create', 'system:fragments:update', 'system:fragments:delete',
       'system:globals:read', 'system:globals:create', 'system:globals:update', 'system:globals:delete',
       'system:extensions:read', 'system:extensions:install', 'system:extensions:uninstall', 'system:extensions:manage',
-      'system:realtime:read', 'system:emails:read', 'system:emails:manage'
+      'system:realtime:read', 'system:emails:read', 'system:emails:manage', 'system:updates:manage'
     ]
   }
 };

package/server/utils/setup/seedIfNew.js

@@ -0,0 +1,21 @@
+import { eq } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { group } from '../../db/schema.js';
+import seedDatabase from './seedDatabase.js';
+
+/*
+  A database with no Administrators group is a new one (the group cannot be deleted), so kempo's groups, permissions and
+  settings are put in it, which is what `scripts/init-db.js` does by hand. It is what lets a new site start from an empty
+  database with no command typed: the tables come from syncCoreSchema, this fills them, and the /setup page makes the
+  first administrator. A database that has the group is never touched.
+*/
+export default async () => {
+  try {
+    const [existing] = await db.select({ name: group.name }).from(group).where(eq(group.name, 'system:Administrators')).limit(1);
+    if(existing) return [null, { seeded: false }];
+    await seedDatabase({ log: () => {} });
+    return [null, { seeded: true }];
+  } catch(error) {
+    return [{ code: 500, msg: `A new database could not be set up: ${String(error.cause?.message || error.message).slice(0, 300)}` }, null];
+  }
+};

package/server/utils/setup/syncCoreSchema.js

@@ -0,0 +1,130 @@
+import { sql } from 'drizzle-orm';
+import db from '../../db/index.js';
+import * as coreSchema from '../../db/schema.js';
+
+/*
+  Brings kempo's own tables in step with the installed version of kempo, so an update never needs a command typed.
+  It runs when the server starts, before the site serves anything.
+
+  It only ever adds. It looks at which of the schema's tables, columns, indexes and constraints the database already
+  has, and asks drizzle-kit's migration generator (the one `drizzle-kit push` is built on) for the difference between
+  "what the database has" and "what the schema says", so the new indexes and foreign keys come out exactly as a push
+  would make them. What the database has is the schema with every missing piece cut out, so the difference can only
+  be additions: it can never contain a DROP or a TRUNCATE, and a table that an extension or the site made is never
+  looked at. A column that kempo no longer has stays where it is. A change to something that already exists (a new
+  type, a NOT NULL) is not detected here: that is what a release's own migration step is for.
+
+  Each statement is applied on its own, so one the database refuses (a new unique index over rows that already break
+  it, a NOT NULL column with no default on a table that has rows) is reported without holding back the rest. Several
+  processes starting together queue on an advisory lock, and the one after the first finds nothing left to do.
+
+  (drizzle-kit's `pushSchema` is not used: it drops the parameters of its own introspection queries, which fails on any
+  table with a composite key and then ends the process, and for a type change it proposes TRUNCATE ... CASCADE.)
+*/
+const LOCK_KEY = 'kempo:sync-core-schema';
+
+const ADDITIVE = [
+  /^CREATE TABLE /i,
+  /^CREATE (UNIQUE )?INDEX /i,
+  /^CREATE TYPE /i,
+  /^ALTER TABLE .+ ADD COLUMN /i,
+  /^ALTER TABLE .+ ADD CONSTRAINT /i,
+];
+
+/* A last check on what the generator produced: anything that is not an addition is never run. */
+export const isAdditive = statement => ADDITIVE.some(pattern => pattern.test(statement.trim()));
+
+/* One plain sentence for a statement, for the log and the Updates screen. */
+export const describe = statement => {
+  const text = statement.trim();
+  const named = (pattern, make) => {
+    const match = text.match(pattern);
+    return match ? make(...match.slice(1)) : null;
+  };
+  return named(/^CREATE TABLE "([^"]+)"/i, table => `Created table ${table}`)
+    ?? named(/^ALTER TABLE "([^"]+)" ADD COLUMN "([^"]+)"/i, (table, column) => `Added column ${table}.${column}`)
+    ?? named(/^CREATE (?:UNIQUE )?INDEX "([^"]+)"/i, index => `Created index ${index}`)
+    ?? named(/^ALTER TABLE "([^"]+)" ADD CONSTRAINT "([^"]+)"/i, (table, constraint) => `Added ${constraint} to ${table}`)
+    ?? text.replace(/\s+/g, ' ').slice(0, 120);
+};
+
+const rowsOf = result => (Array.isArray(result) ? result : result.rows);
+
+/* The names of what the database already has in the public schema. */
+const readDatabase = async executor => {
+  const names = async (query, field) => new Set(rowsOf(await executor.execute(query)).map(row => row[field]));
+  const columns = rowsOf(await executor.execute(sql`select table_name, column_name from information_schema.columns where table_schema = 'public'`));
+  return {
+    tables: await names(sql`select table_name from information_schema.tables where table_schema = 'public'`, 'table_name'),
+    columns: new Set(columns.map(row => `${row.table_name}.${row.column_name}`)),
+    indexes: await names(sql`select indexname from pg_indexes where schemaname = 'public'`, 'indexname'),
+    constraints: await names(sql`select conname from pg_constraint join pg_namespace on pg_namespace.oid = pg_constraint.connamespace where nspname = 'public'`, 'conname'),
+    enums: await names(sql`select typname from pg_type join pg_namespace on pg_namespace.oid = pg_type.typnamespace where typtype = 'e' and nspname = 'public'`, 'typname'),
+  };
+};
+
+/* The schema snapshot with everything the database lacks cut out: what drizzle-kit would see if it had introspected the database. */
+const withoutMissing = (snapshot, existing) => {
+  const prev = structuredClone(snapshot);
+  for(const key of Object.keys(prev.enums)){
+    if(!existing.enums.has(prev.enums[key].name)) delete prev.enums[key];
+  }
+  for(const [key, table] of Object.entries(prev.tables)){
+    if(!existing.tables.has(table.name)){
+      delete prev.tables[key];
+      continue;
+    }
+    for(const name of Object.keys(table.columns)){
+      if(!existing.columns.has(`${table.name}.${name}`)) delete table.columns[name];
+    }
+    for(const name of Object.keys(table.indexes)){
+      if(!existing.indexes.has(name)) delete table.indexes[name];
+    }
+    for(const group of [table.foreignKeys, table.uniqueConstraints, table.compositePrimaryKeys ?? {}]){
+      for(const id of Object.keys(group)){
+        if(!existing.constraints.has(group[id].name)) delete group[id];
+      }
+    }
+  }
+  return prev;
+};
+
+/* What the last run did, for the Updates screen. */
+let lastRun = { ran: false, applied: [], failed: [] };
+
+export const getSchemaSyncResult = () => lastRun;
+
+/*
+  Resolves to [error, { applied, failed }]: `applied` is a list of sentences, `failed` is { change, reason } for what
+  the database refused. `schema` and `executor` are for tests and extensions: other tables, in another database.
+*/
+export default async ({ schema = coreSchema, executor = db } = {}) => {
+  try {
+    const { generateDrizzleJson, generateMigration } = await import('drizzle-kit/api');
+    const wanted = generateDrizzleJson(schema);
+    const result = { applied: [], failed: [] };
+
+    await executor.transaction(async tx => {
+      await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${LOCK_KEY}::text))`);
+      const statements = await generateMigration(withoutMissing(wanted, await readDatabase(tx)), wanted);
+
+      for(const statement of statements){
+        if(!isAdditive(statement)){
+          result.failed.push({ change: describe(statement), reason: 'Kempo only adds to its tables, so this was not run' });
+          continue;
+        }
+        try {
+          await tx.transaction(inner => inner.execute(sql.raw(statement)));
+          result.applied.push(describe(statement));
+        } catch(error) {
+          result.failed.push({ change: describe(statement), reason: String(error.cause?.message || error.message).slice(0, 300) });
+        }
+      }
+    });
+
+    if(schema === coreSchema) lastRun = { ran: true, ...result };
+    return [null, result];
+  } catch(error) {
+    return [{ code: 500, msg: `The database could not be checked against this version of kempo: ${String(error.cause?.message || error.message).slice(0, 300)}` }, null];
+  }
+};

package/server/utils/setup/systemPermissions.js

@@ -55,6 +55,8 @@ export const SYSTEM_PERMISSIONS = [
   { name: 'system:emails:read', description: 'View the log of emails, including what they said' },
   { name: 'system:emails:manage', description: 'Send a test email and try failed emails again' },
 
+  { name: 'system:updates:manage', description: 'See, check for and install kempo updates, which restarts the server' },
+
   { name: 'system:admin:access', description: 'Access admin panel' },
 ];
 

package/server/utils/updates/applyStagedUpdate.js

@@ -0,0 +1,95 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { and, eq, like } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { notification } from '../../db/schema.js';
+import { RUNNING_VERSION } from './runtime.js';
+import backupDatabase from './backupDatabase.js';
+import { restartMode, scheduleRestart } from './restart.js';
+import { clearState, paths, readState, requestSwitch } from './siteLayout.js';
+import { applyStarterFiles } from './starterFiles.js';
+import { PACKAGE } from './helpers.js';
+import triggerHook from '../hooks/triggerHook.js';
+import markHandled from '../notifications/markHandled.js';
+
+let switching = false;
+
+/* The notifications about extension updates are done with once the owner has acted on them. */
+const resolveExtensionNotices = async () => {
+  const rows = await db.select({ id: notification.id }).from(notification).where(and(eq(notification.owner, PACKAGE), like(notification.dedupeKey, 'extension-updates:%')));
+  for(const { id } of rows) await markHandled({ notificationId: id });
+};
+
+/*
+  Switches a site that runs from a Docker volume to what prepareUpdate staged (a new kempo, new extensions, or both): replaces
+  the starter files the owner never touched (and, when the owner confirms, the ones a security fix must replace, keeping a
+  copy of each), backs the database up first if anything in the update changes data, then asks for the switch and restarts.
+  The startup script moves the code into place while nothing is running, the site is only unavailable for the restart, and
+  at that start each extension is brought up to date (reconcileExtensions) before the site serves anything.
+
+  `confirm` is { forced: true, breaking: true }: the owner has accepted that edited files will be replaced, and that an
+  update which changes data (a data migration in kempo, or a new major version of an extension) can only be undone from a
+  backup. Without them, an update that needs them answers 409 with `details` saying which, and does nothing.
+
+  Resolves to [error, { from, to, restart, breaking }].
+*/
+export default async ({ confirm = {}, siteRoot = process.env.KEMPO_SITE_ROOT, cwd = process.cwd(), restart = scheduleRestart, backup = backupDatabase } = {}) => {
+  if(!siteRoot){
+    return [{ code: 409, msg: 'This site is not set up to switch to a prepared update' }, null];
+  }
+  if(switching){
+    return [{ code: 409, msg: 'A switch is already under way' }, null];
+  }
+
+  const staged = readState(siteRoot, 'staged');
+  if(!staged || !existsSync(join(staged.dir, 'node_modules'))){
+    return [{ code: 409, msg: 'No update is ready: prepare one first' }, null];
+  }
+  if(readState(siteRoot, 'switch')){
+    return [{ code: 409, msg: 'The last switch has not finished proving itself yet' }, null];
+  }
+
+  const { plan } = staged;
+  if(plan.files.forced.length && !confirm.forced){
+    return [{ code: 409, msg: 'This update must replace files you have edited', details: { confirm: 'forced', files: plan.files.forced } }, null];
+  }
+  if(plan.breaking && !confirm.breaking){
+    return [{ code: 409, msg: 'This update changes your data and can only be undone from a backup', details: { confirm: 'breaking', upgrades: plan.upgrades.filter(upgrade => upgrade.breaking), extensions: plan.extensions.filter(extension => extension.breaking).map(extension => extension.name) } }, null];
+  }
+
+  switching = true;
+  try {
+    let dbBackup = null;
+    if(plan.breaking){
+      dbBackup = join(paths(siteRoot).state, 'backups', `${staged.id}.sql.gz`);
+      const [backupError] = await backup({ file: dbBackup });
+      if(backupError) return [backupError, null];
+    }
+
+    const filesBackup = staged.kempoUpdate
+      ? applyStarterFiles({
+        cwd,
+        newRoot: join(staged.dir, 'node_modules', 'kempo'),
+        version: staged.version,
+        plan: plan.files,
+        includeForced: Boolean(confirm.forced),
+        backupDir: join(paths(siteRoot).state, 'backups', `${staged.id}-files`)
+      })
+      : null;
+
+    requestSwitch({ siteRoot, id: staged.id, version: staged.version, source: staged.dir, kind: 'update', breaking: plan.breaking, packages: staged.packages, dbBackup, filesBackup });
+    clearState(siteRoot, 'staged');
+
+    if(staged.kempoUpdate){
+      await markHandled({ owner: PACKAGE, dedupeKey: `update:${staged.version}` });
+      await triggerHook('kempo:updated', { oldVersion: RUNNING_VERSION, newVersion: staged.version, packages: staged.packages });
+    }
+    if(plan.extensions.length) await resolveExtensionNotices();
+    restart();
+    return [null, { from: RUNNING_VERSION, to: staged.version, restart: restartMode(), breaking: plan.breaking }];
+  } catch(error) {
+    return [{ code: 500, msg: `The switch could not be requested: ${error.message}` }, null];
+  } finally {
+    switching = false;
+  }
+};

package/server/utils/updates/applyUpdate.js

@@ -0,0 +1,76 @@
+import { PACKAGE, compareVersions } from './helpers.js';
+import extensionTargets from './extensionTargets.js';
+import { RUNNING_VERSION } from './runtime.js';
+import fetchManifest from './fetchManifest.js';
+import getInstallInfo from './getInstallInfo.js';
+import { installedVersion, npmFailure, runNpm, targetsFor } from './npm.js';
+import { restartMode, scheduleRestart } from './restart.js';
+import triggerHook from '../hooks/triggerHook.js';
+import markHandled from '../notifications/markHandled.js';
+
+let updating = false;
+let restarting = false;
+
+/*
+  For a site that does not run from a Docker volume (see prepareUpdate for one that does): installs in place.
+
+  Installs a newer version of kempo and/or of installed extensions (`version` null leaves kempo as it is, `extensions` are
+  names), then restarts the server so that it runs them, and at that start each extension is brought up to date
+  (reconcileExtensions). Without `version` it is the newest kempo. A newer kempo can need newer kempo-server, kempo-ui or kempo-css than the site has, so any peer
+  that no longer meets the new version's minimum is updated in the same install. Older versions are refused.
+
+  Returns once the install has finished and the restart is scheduled, a second later, so the caller can answer
+  the request first. The rest are for tests.
+*/
+export default async ({ version = 'latest', extensions = [], cwd = process.cwd(), install = getInstallInfo({ cwd }), run = runNpm, restart = scheduleRestart, fetcher, executor } = {}) => {
+  const { canUpdate, reason } = install;
+  if(!canUpdate){
+    return [{ code: 409, msg: reason }, null];
+  }
+  if(version === null && !extensions.length){
+    return [{ code: 400, msg: 'Choose something to update' }, null];
+  }
+  if(updating){
+    return [{ code: 409, msg: 'An update is already running' }, null];
+  }
+
+  updating = true;
+  try {
+    let manifest = null;
+    if(version !== null){
+      const [manifestError, found] = await fetchManifest({ version, fetcher });
+      if(manifestError) return [manifestError, null];
+      if(compareVersions(found.version, RUNNING_VERSION) <= 0){
+        return [{ code: 409, msg: `Version ${RUNNING_VERSION} is already running` }, null];
+      }
+      manifest = found;
+    }
+
+    const [targetsError, wanted] = await extensionTargets({ names: extensions, kempoVersion: manifest?.version ?? RUNNING_VERSION, root: cwd, fetcher, ...(executor ? { executor } : {}) });
+    if(targetsError) return [targetsError, null];
+
+    const targets = [...(manifest ? targetsFor({ manifest, dir: cwd }) : []), ...wanted.targets];
+
+    try {
+      await run(targets, cwd);
+    } catch(error) {
+      return [{ code: 500, msg: `The update could not be installed: ${npmFailure(error)}` }, null];
+    }
+
+    const missing = [...(manifest ? [{ name: PACKAGE, to: manifest.version }] : []), ...wanted.items].find(item => installedVersion(cwd, item.name) !== item.to);
+    if(missing){
+      return [{ code: 500, msg: `npm finished but ${missing.name} ${missing.to} is not installed` }, null];
+    }
+
+    if(manifest){
+      await markHandled({ owner: PACKAGE, dedupeKey: `update:${manifest.version}` });
+      await triggerHook('kempo:updated', { oldVersion: RUNNING_VERSION, newVersion: manifest.version, packages: targets });
+    }
+    restarting = true;
+    restart();
+
+    return [null, { from: RUNNING_VERSION, to: manifest?.version ?? RUNNING_VERSION, packages: targets, restart: restartMode() }];
+  } finally {
+    updating = restarting;
+  }
+};

package/server/utils/updates/backupDatabase.js

@@ -0,0 +1,35 @@
+import { spawn } from 'child_process';
+import { createWriteStream, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { createGzip } from 'zlib';
+import { pipeline } from 'stream/promises';
+
+/*
+  A copy of the whole database in `file`, as gzipped plain SQL that restores itself (it drops what it replaces), taken with
+  pg_dump. It is what an update that changes data is put back from, so without pg_dump (the Docker image has it) such an
+  update is refused rather than made without a way back. `spawner` is for tests.
+*/
+export default async ({ file, url = process.env.DATABASE_URL, spawner = spawn } = {}) => {
+  if(!file) return [{ code: 400, msg: 'A file to write the backup to is required' }, null];
+  if(!url) return [{ code: 500, msg: 'DATABASE_URL is not set, so the database cannot be backed up' }, null];
+
+  mkdirSync(dirname(file), { recursive: true });
+  const dump = spawner('pg_dump', ['--clean', '--if-exists', '--no-owner', '--no-privileges', url], { stdio: ['ignore', 'pipe', 'pipe'] });
+  let errors = '';
+  dump.stderr?.on('data', chunk => { errors += chunk; });
+  const ended = new Promise(resolve => {
+    dump.on('error', error => resolve(error.code === 'ENOENT' ? 'missing' : error.message));
+    dump.on('exit', code => resolve(code === 0 ? null : `pg_dump ended with ${code}: ${errors.trim().split('\n').slice(-2).join(' ')}`));
+  });
+
+  try {
+    await pipeline(dump.stdout, createGzip(), createWriteStream(file));
+  } catch(error) {
+    return [{ code: 500, msg: `The database backup could not be written: ${error.message}` }, null];
+  }
+
+  const problem = await ended;
+  if(problem === 'missing') return [{ code: 501, msg: 'pg_dump is not installed here, so the data cannot be backed up and this update will not be made without one' }, null];
+  if(problem) return [{ code: 500, msg: `The database could not be backed up: ${problem}` }, null];
+  return [null, { file }];
+};

package/server/utils/updates/discardUpdate.js

@@ -0,0 +1,11 @@
+import { rmSync } from 'fs';
+import { clearState, paths, readState } from './siteLayout.js';
+
+/* Throws away a staged update that was not switched to, which frees its disk space. */
+export default ({ siteRoot = process.env.KEMPO_SITE_ROOT } = {}) => {
+  if(!siteRoot) return [{ code: 409, msg: 'This site has no staged updates' }, null];
+  if(readState(siteRoot, 'switch')) return [{ code: 409, msg: 'A switch is under way' }, null];
+  rmSync(paths(siteRoot).staging, { recursive: true, force: true });
+  clearState(siteRoot, 'staged');
+  return [null, { discarded: true }];
+};

package/server/utils/updates/extensionTargets.js

@@ -0,0 +1,101 @@
+import { join } from 'path';
+import { eq } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { extension } from '../../db/schema.js';
+import { compareVersions, isBreakingBump, isVersion, lowerBound } from './helpers.js';
+import fetchManifest from './fetchManifest.js';
+import { installedVersion } from './npm.js';
+import readKempoConfig from '../extensions/readKempoConfig.js';
+import checkClaims from '../extensions/checkClaims.js';
+import { normalizeAliases } from '../extensions/aliases.js';
+import { normalizeScopes, scopeNames } from '../extensions/scopes.js';
+import { NAME_PATTERN } from '../extensions/marketplaceClient.js';
+
+/*
+  Checks a set of extension updates against npm and the site, and says what to install: for each name, that it is installed,
+  that npm has a newer version, and that the new version does not need a newer kempo than the one that will be running
+  (`kempoVersion`: the one being installed alongside, or the one running). Nothing is installed here.
+
+  Resolves to [error, { targets, items }] where `targets` are `name@version` for npm and each item is
+  { name, row, from, to, major }. The first problem is the error, with the extension's name in it.
+*/
+export default async ({ names, kempoVersion, executor = db, root = process.cwd(), fetcher }) => {
+  const items = [];
+  const targets = [];
+
+  for(const name of [...new Set(names)]){
+    if(typeof name !== 'string' || !NAME_PATTERN.test(name)){
+      return [{ code: 400, msg: `"${name}" is not a valid extension name` }, null];
+    }
+    const [row] = await executor.select().from(extension).where(eq(extension.name, name)).limit(1);
+    if(!row){
+      return [{ code: 404, msg: `${name} is not installed` }, null];
+    }
+
+    const [error, manifest] = await fetchManifest({ name, fetcher });
+    if(error) return [{ ...error, msg: `${name}: ${error.msg}` }, null];
+
+    const from = installedVersion(root, name) ?? row.version;
+    if(!isVersion(from) || compareVersions(manifest.version, from) <= 0){
+      return [{ code: 409, msg: `${name} is already up to date` }, null];
+    }
+
+    const needs = manifest.peerDependencies.kempo ? lowerBound(manifest.peerDependencies.kempo) : null;
+    if(needs && compareVersions(needs, kempoVersion) > 0){
+      return [{ code: 409, msg: `${name} ${manifest.version} needs Kempo ${needs} or newer: update Kempo first, or at the same time` }, null];
+    }
+
+    items.push({ name, row, from, to: manifest.version, major: isBreakingBump(from, manifest.version) });
+    targets.push(`${name}@${manifest.version}`);
+  }
+
+  return [null, { targets, items }];
+};
+
+const countNew = (next = [], old = [], key = item => item.name) => {
+  const had = new Set(old.map(key));
+  return next.filter(item => !had.has(key(item))).length;
+};
+
+/*
+  What each updated extension would change, read from the staged copy of its package against what was recorded when it was
+  installed: how many permissions, settings, groups, dashboard widgets and scheduled jobs it adds, whether it is breaking (a
+  new major version, a new minor one while the major is 0, or the new version says `"breaking": true` in its kempo-config.json), and whether the addresses it
+  claims collide with another extension's, which stops the update. Resolves to [error, [entry]].
+*/
+export const extensionPlan = async ({ dir, items, executor }) => {
+  const plan = [];
+  for(const item of items){
+    let next;
+    try {
+      ({ kempo: next } = await readKempoConfig(join(dir, 'node_modules', item.name)));
+    } catch {
+      return [{ code: 500, msg: `${item.name} ${item.to} was not found in the staged copy` }, null];
+    }
+
+    const [scopesError] = normalizeScopes(next);
+    const [aliasesError] = scopesError ? [null] : normalizeAliases(next.aliases, scopeNames(next));
+    const [claimsError] = scopesError || aliasesError || !item.row.enabled
+      ? [null]
+      : await checkClaims({ names: [item.name], verb: 'update', kempo: { [item.name]: next }, ...(executor ? { executor } : {}) });
+    const refusal = scopesError || aliasesError || claimsError;
+    if(refusal) return [{ code: 409, msg: `${item.name} ${item.to} cannot be installed: ${refusal.msg}` }, null];
+
+    const old = item.row.kempo || {};
+    plan.push({
+      name: item.name,
+      from: item.from,
+      to: item.to,
+      major: item.major,
+      breaking: item.major || next.breaking === true,
+      adds: {
+        permissions: countNew(next.permissions, old.permissions),
+        settings: countNew(next.settings, old.settings),
+        groups: countNew(next.groups, old.groups),
+        widgets: countNew(next.widgets, old.widgets, widget => widget.key),
+        jobs: countNew(next.jobs, old.jobs)
+      }
+    });
+  }
+  return [null, plan];
+};