kempo 4.8.0 → 4.9.0

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

package/server/utils/updates/fetchManifest.js

@@ -0,0 +1,26 @@
+import { DEFAULT_REGISTRY, PACKAGE, isVersion } from './helpers.js';
+import { NAME_PATTERN } from '../extensions/marketplaceClient.js';
+
+/*
+  Reads one version's manifest of a package (kempo by default, or an extension) from the npm registry, "latest" by default.
+  Resolves to [error, { name, version, peerDependencies }].
+*/
+export default async ({ name = PACKAGE, version = 'latest', registry = process.env.KEMPO_NPM_REGISTRY || DEFAULT_REGISTRY, fetcher = fetch } = {}) => {
+  if(typeof name !== 'string' || !NAME_PATTERN.test(name)){
+    return [{ code: 400, msg: 'Package name is not valid' }, null];
+  }
+  if(version !== 'latest' && !isVersion(version)){
+    return [{ code: 400, msg: 'Version is not valid' }, null];
+  }
+
+  try {
+    const res = await fetcher(`${registry.replace(/\/+$/, '')}/${name.replace('/', '%2F')}/${version}`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(10000) });
+    if(res.status === 404) return [{ code: 404, msg: `${name}${version === 'latest' ? '' : ` ${version}`} was not found on npm` }, null];
+    if(!res.ok) return [{ code: 502, msg: `npm answered ${res.status}` }, null];
+    const manifest = await res.json();
+    if(!isVersion(manifest?.version)) return [{ code: 502, msg: 'npm did not return a usable version' }, null];
+    return [null, { name, version: manifest.version, peerDependencies: manifest.peerDependencies ?? {} }];
+  } catch {
+    return [{ code: 502, msg: 'npm could not be reached' }, null];
+  }
+};

package/server/utils/updates/getExtensionUpdates.js

@@ -0,0 +1,70 @@
+import { join } from 'path';
+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 readKempoConfig from '../extensions/readKempoConfig.js';
+
+/* The last answer npm gave for the installed extensions, kept for the process like the one for kempo itself. */
+let known = null;
+let checkError = null;
+
+export const resetExtensionUpdates = () => {
+  known = null;
+  checkError = null;
+};
+
+const CONCURRENCY = 4;
+
+const installedVersionOf = async (root, row) => {
+  try {
+    return (await readKempoConfig(join(root, 'node_modules', row.name))).pkg.version;
+  } catch {
+    return null;
+  }
+};
+
+/*
+  Asks npm for the newest version of every installed extension, four at a time, and lists those that are newer than what is
+  on disk: [{ name, installedVersion, latestVersion, major, kempoRequired }]. `kempoRequired` is the lowest kempo the new
+  version asks for, which can be newer than the one running (then it can only be updated together with kempo).
+  An extension that is not on npm (a git-only one) or whose answer was an error is left out; if every answer was an
+  error, `checkError` says npm could not be reached. Asks when `force` is set or the last answer is older than `maxAgeMs`;
+  `offline` never asks.
+*/
+export default async ({ force = false, offline = false, maxAgeMs = 3600000, fetcher, executor = db, root = process.cwd() } = {}) => {
+  if(!offline && (force || !known || Date.now() - known.checkedAt > maxAgeMs)){
+    const rows = await executor.select().from(extension);
+    const updates = [];
+    let failures = 0;
+    let next = 0;
+
+    const work = async () => {
+      while(next < rows.length){
+        const row = rows[next++];
+        const installedVersion = await installedVersionOf(root, row);
+        if(!isVersion(installedVersion)) continue;
+        const [error, manifest] = await fetchManifest({ name: row.name, fetcher });
+        if(error){
+          if(error.code !== 404) failures++;
+          continue;
+        }
+        if(compareVersions(manifest.version, installedVersion) > 0){
+          updates.push({
+            name: row.name,
+            installedVersion,
+            latestVersion: manifest.version,
+            major: isBreakingBump(installedVersion, manifest.version),
+            kempoRequired: manifest.peerDependencies.kempo ? lowerBound(manifest.peerDependencies.kempo) : null
+          });
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: CONCURRENCY }, work));
+
+    checkError = rows.length && failures === rows.length ? 'npm could not be reached' : null;
+    if(!checkError) known = { checkedAt: Date.now(), updates: updates.sort((a, b) => a.name.localeCompare(b.name)) };
+  }
+
+  return [null, { updates: known?.updates ?? [], checkedAt: known ? new Date(known.checkedAt).toISOString() : null, checkError }];
+};

package/server/utils/updates/getInstallInfo.js

@@ -0,0 +1,25 @@
+import { readFileSync } from 'fs';
+import { join, sep } from 'path';
+import { PACKAGE } from './helpers.js';
+import { PACKAGE_ROOT } from './runtime.js';
+
+/*
+  Whether this site can update kempo by installing a new version of it. A checkout that is linked or run
+  from source (this repository, or a site using `npm run link:local`) is refused: `npm install` would
+  replace the link with the registry copy and throw the local work away.
+*/
+export default ({ cwd = process.cwd(), packageRoot = PACKAGE_ROOT } = {}) => {
+  if(!packageRoot.startsWith(join(cwd, 'node_modules') + sep)){
+    return { canUpdate: false, reason: 'Kempo is linked from a local checkout, not installed from npm.' };
+  }
+
+  try {
+    const spec = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')).dependencies?.[PACKAGE];
+    if(!spec) return { canUpdate: false, reason: "Kempo is not a dependency in this site's package.json." };
+    if(/^(file|link|git|github|https?):/.test(spec)) return { canUpdate: false, reason: `This site's package.json points kempo at "${spec}", not at an npm version.` };
+  } catch {
+    return { canUpdate: false, reason: "This site's package.json could not be read." };
+  }
+
+  return { canUpdate: true, reason: null };
+};

package/server/utils/updates/getUpdateStatus.js

@@ -0,0 +1,57 @@
+import { PACKAGE, compareVersions, isBreakingBump } from './helpers.js';
+import { RUNNING_VERSION, BOOT_ID } from './runtime.js';
+import fetchManifest from './fetchManifest.js';
+import getInstallInfo from './getInstallInfo.js';
+import { restartMode } from './restart.js';
+import releaseStatus from './releaseStatus.js';
+import getExtensionUpdates, { resetExtensionUpdates } from './getExtensionUpdates.js';
+import { getReconcileResult } from '../extensions/reconcileExtensions.js';
+import { getSchemaSyncResult } from '../setup/syncCoreSchema.js';
+
+/* The last answer npm gave, kept for the process so that opening the screen does not ask npm every time. */
+let known = null;
+let checkError = null;
+
+export const resetUpdateStatus = () => {
+  resetExtensionUpdates();
+  known = null;
+  checkError = null;
+};
+
+/*
+  Where this site stands: what is running, the newest version on npm and whether it can be installed here.
+  Asks npm when `force` is set or the last answer is older than `maxAgeMs`; a failed ask keeps the last
+  good answer and reports why in `checkError`. `offline` never asks, for a caller that must answer at once.
+*/
+export default async ({ force = false, offline = false, maxAgeMs = 3600000, fetcher, install = getInstallInfo(), executor } = {}) => {
+  if(!offline && (force || !known || Date.now() - known.checkedAt > maxAgeMs)){
+    const [error, manifest] = await fetchManifest({ fetcher });
+    if(error){
+      checkError = error.msg;
+    } else {
+      checkError = null;
+      known = { latestVersion: manifest.version, checkedAt: Date.now() };
+    }
+  }
+
+  const [, extensionUpdates] = await getExtensionUpdates({ force, offline, maxAgeMs, fetcher, ...(executor ? { executor } : {}) });
+  const latestVersion = known?.latestVersion ?? null;
+  const updateAvailable = latestVersion !== null && compareVersions(latestVersion, RUNNING_VERSION) > 0;
+
+  return [null, {
+    runningVersion: RUNNING_VERSION,
+    bootId: BOOT_ID,
+    latestVersion,
+    updateAvailable,
+    major: updateAvailable && isBreakingBump(RUNNING_VERSION, latestVersion),
+    checkedAt: known ? new Date(known.checkedAt).toISOString() : null,
+    checkError,
+    restart: restartMode(),
+    database: getSchemaSyncResult(),
+    extensionUpdates,
+    extensionsRun: getReconcileResult(),
+    ...releaseStatus(),
+    npmUrl: `https://www.npmjs.com/package/${PACKAGE}`,
+    ...install
+  }];
+};

package/server/utils/updates/helpers.js

@@ -0,0 +1,30 @@
+export const PACKAGE = 'kempo';
+
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+/* Only plain releases are ever installed by an update: no tags, ranges or prereleases, so nothing here can reach a shell as anything else. */
+export const isVersion = value => typeof value === 'string' && /^\d+\.\d+\.\d+$/.test(value);
+
+/* -1, 0 or 1 for a compared with b, both plain versions. */
+export const compareVersions = (a, b) => {
+  const left = a.split('.').map(Number);
+  const right = b.split('.').map(Number);
+  for(let i = 0; i < 3; i++){
+    if(left[i] !== right[i]) return left[i] > right[i] ? 1 : -1;
+  }
+  return 0;
+};
+
+/*
+  Whether going from one plain version to a higher one may break what depended on it, by semver: a new major version, and
+  while the major is still 0 a new minor version too (0.1.x to 0.2.0 is the breaking step there, which is what npm's own ^0.1.1
+  assumes). Every extension kempo has is still 0.x, so this is what makes its updates warn.
+*/
+export const isBreakingBump = (from, to) => {
+  const [fromMajor, fromMinor] = from.split('.').map(Number);
+  const [toMajor, toMinor] = to.split('.').map(Number);
+  return fromMajor === 0 ? (toMajor > 0 || toMinor > fromMinor) : toMajor > fromMajor;
+};
+
+/* The version a peer range such as ">=2.2.5" or "^3.4.0" starts at, or null for one that names none ("*"). */
+export const lowerBound = range => String(range).match(/\d+\.\d+\.\d+/)?.[0] ?? null;

package/server/utils/updates/notifySchemaAttention.js

@@ -0,0 +1,35 @@
+import { createHash } from 'crypto';
+import { and, eq } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { notification } from '../../db/schema.js';
+import createNotification from '../notifications/createNotification.js';
+import { getSchemaSyncResult } from '../setup/syncCoreSchema.js';
+import { getReconcileResult } from '../extensions/reconcileExtensions.js';
+import { PACKAGE } from './helpers.js';
+
+/*
+  After the server starts: when syncing kempo's tables left a change that the database refused, or an extension could not be
+  brought up to date, tell everyone who can update kempo, once for each distinct set of problems.
+  Raising the same notification at every start would mark it unread for everyone each time.
+*/
+export default async ({ result = getSchemaSyncResult(), extensions = getReconcileResult() } = {}) => {
+  const problems = [
+    ...result.failed.map(({ change, reason }) => `${change} (${reason})`),
+    ...extensions.failed.map(({ name, to, reason }) => `${name} ${to} could not be brought up to date (${reason})`)
+  ];
+  if(!problems.length) return [null];
+
+  const dedupeKey = `schema:${createHash('sha256').update(problems.join('\n')).digest('hex').slice(0, 16)}`;
+  const [existing] = await db.select({ id: notification.id }).from(notification).where(and(eq(notification.owner, PACKAGE), eq(notification.dedupeKey, dedupeKey))).limit(1);
+  if(existing) return [null];
+
+  return createNotification({
+    owner: PACKAGE,
+    title: 'An update needs attention',
+    message: `Kempo started, but ${problems.length === 1 ? 'one thing was' : `${problems.length} things were`} not applied: ${problems.slice(0, 3).join('; ')}${problems.length > 3 ? '; and more' : ''}.`,
+    level: 'error',
+    permission: 'system:updates:manage',
+    dedupeKey,
+    actions: [{ label: 'View details', href: '/admin/updates' }]
+  });
+};

package/server/utils/updates/npm.js

@@ -0,0 +1,41 @@
+import { execFile } from 'child_process';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { promisify } from 'util';
+import { PACKAGE, compareVersions, lowerBound } from './helpers.js';
+import { NAME_PATTERN } from '../extensions/marketplaceClient.js';
+
+const execute = promisify(execFile);
+
+/* `npm install` of already validated targets (plain names and x.y.z or "latest") in `cwd`. */
+export const runNpm = (args, cwd) => execute('npm', ['install', ...args, '--no-audit', '--no-fund'], {
+  cwd,
+  shell: process.platform === 'win32',
+  timeout: 10 * 60 * 1000,
+  maxBuffer: 10 * 1024 * 1024
+});
+
+export const installedVersion = (dir, name) => {
+  try {
+    return JSON.parse(readFileSync(join(dir, 'node_modules', name, 'package.json'), 'utf8')).version;
+  } catch {
+    return null;
+  }
+};
+
+/*
+  What to install for a manifest of kempo: kempo itself, and any peer (kempo-server, kempo-ui, kempo-css) that is installed
+  in `dir` at a version below what the new kempo asks for at least. A peer that already meets it is left alone.
+*/
+export const targetsFor = ({ manifest, dir }) => {
+  const targets = [`${PACKAGE}@${manifest.version}`];
+  for(const [name, range] of Object.entries(manifest.peerDependencies)){
+    const bound = lowerBound(range);
+    const installed = installedVersion(dir, name);
+    if(NAME_PATTERN.test(name) && bound && installed && compareVersions(installed, bound) < 0) targets.push(`${name}@latest`);
+  }
+  return targets;
+};
+
+/* The last lines of what npm said when it failed. */
+export const npmFailure = error => String(error.stderr || error.message || '').trim().split('\n').filter(Boolean).slice(-3).join(' ');