kempo 4.6.1 → 4.7.0

package/server/utils/extensions/installExtension.js

@@ -14,6 +14,11 @@ import createTablesFromSchema from './createTablesFromSchema.js';
 import readKempoConfig from './readKempoConfig.js';
 import { invalidateScopeCache } from './scopeCache.js';
 import { getUnmetDependencies } from './dependencies.js';
+import registerJobs from '../scheduler/registerJobs.js';
+import { normalizeJobs } from '../scheduler/helpers.js';
+import { normalizeAliases } from './aliases.js';
+import { normalizeScopes, scopeNames } from './scopes.js';
+import checkClaims from './checkClaims.js';
 
 export default async ({ name }) => {
   if(!name){
@@ -48,6 +53,22 @@ export default async ({ name }) => {
     return [{ code: 409, msg: `Requires ${unmet.join(', ')} to be installed and enabled first` }, null];
   }
 
+  const [jobsError] = normalizeJobs(kempoConfig.jobs);
+  if(jobsError) return [jobsError, null];
+
+  const [scopesError] = normalizeScopes(kempoConfig);
+  if(scopesError) return [scopesError, null];
+
+  const [aliasesError] = normalizeAliases(kempoConfig.aliases, scopeNames(kempoConfig));
+  if(aliasesError) return [aliasesError, null];
+
+  /*
+    An address can belong to one extension only. Installing a second one that claims it would leave
+    it with no public pages and no error, so it is refused here and the first has to be disabled.
+  */
+  const [claimsError] = await checkClaims({ names: [name], verb: 'install', kempo: { [name]: kempoConfig } });
+  if(claimsError) return [claimsError, null];
+
   /*
     Create tables from declarative schema
   */
@@ -131,6 +152,17 @@ export default async ({ name }) => {
     }
   }
 
+  /*
+    Register declarative scheduled jobs. Like a widget, a job that cannot be registered (a site that has
+    not applied the scheduledJob table yet) is reported and skipped rather than failing the install.
+  */
+  if((kempoConfig.jobs || []).length){
+    const [registerError] = await registerJobs({ owner: name, jobs: kempoConfig.jobs });
+    if(registerError){
+      console.warn(`[${name}] scheduled jobs were not registered: ${registerError.msg}`);
+    }
+  }
+
   const now = new Date();
   const entry = {
     name,

package/server/utils/extensions/installFromCatalog.js

@@ -6,7 +6,7 @@ import { eq } from 'drizzle-orm';
 import installExtension from './installExtension.js';
 import installPackage from './installPackage.js';
 import enableExtension from './enableExtension.js';
-import { NAME_PATTERN } from './catalogClient.js';
+import { NAME_PATTERN } from './marketplaceClient.js';
 
 const isInstalled = async name => {
   const [row] = await db.select({ name: extension.name }).from(extension).where(eq(extension.name, name)).limit(1);

package/server/utils/extensions/installPackage.js

@@ -1,6 +1,6 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { NAME_PATTERN } from './catalogClient.js';
+import { NAME_PATTERN } from './marketplaceClient.js';
 
 const run = promisify(execFile);
 

package/server/utils/extensions/{catalogClient.js → marketplaceClient.js}

@@ -181,12 +181,15 @@ export const createCatalogClient = ({ baseUrl = DEFAULT_CATALOG_URL, fetchImpl =
   };
 
   return {
-    list: ({ search, sort, limit, offset } = {}) => {
+    /* `exclude` is a list of extension names to leave out, which is how a site hides what it has installed. */
+    list: ({ search, sort, limit, offset, exclude } = {}) => {
       const query = new URLSearchParams();
       if(search) query.set('search', String(search).slice(0, 100));
       if(sort) query.set('sort', String(sort));
       if(limit) query.set('limit', String(limit));
       if(offset) query.set('offset', String(offset));
+      const excluded = (Array.isArray(exclude) ? exclude : []).filter(name => NAME_PATTERN.test(name || '')).slice(0, 500);
+      if(excluded.length) query.set('exclude', excluded.join(','));
       return read(`/extensions${query.size ? `?${query}` : ''}`, normalizePage);
     },
 

package/server/utils/extensions/readKempoConfig.js

@@ -2,8 +2,8 @@ import { join } from 'path';
 import { readFile } from 'fs/promises';
 
 /*
-  What an installed extension declares to kempo: its `public-scope`, `docs`, `git`, `schema`, `hooks`,
-  `permissions`, `settings`, `groups`, `dependencies` and `widgets`.
+  What an installed extension declares to kempo: its `public-scope` and `public-scopes`, `docs`, `git`, `schema`, `hooks`,
+  `permissions`, `settings`, `groups`, `dependencies`, `widgets`, `jobs` and `aliases`.
 
   It lives in the extension's kempo-config.json, which is the one place it is written. package.json's own
   `kempo` field is still read, as the fallback for an older extension that put everything there, and

package/server/utils/extensions/scopeCache.js

@@ -3,7 +3,20 @@ import { extension } from '../../db/schema.js';
 
 let cache = null;
 
-export const invalidateScopeCache = () => { cache = null; };
+const listeners = new Set();
+
+/*
+  For what has to follow the set of enabled extensions, such as menus holding an extension's items.
+  Called after every install, enable, disable and uninstall; a listener's failure never reaches them.
+*/
+export const onExtensionsChanged = listener => listeners.add(listener);
+
+export const invalidateScopeCache = () => {
+  cache = null;
+  for(const listener of listeners){
+    Promise.resolve().then(listener).catch(error => console.error('[kempo] An extension change listener failed:', error.message));
+  }
+};
 
 /* One read of the extension table serves both questions, until an install/enable/disable/uninstall. */
 const load = async () => {

package/server/utils/extensions/scopes.js

@@ -0,0 +1,72 @@
+/*
+  The addresses an extension answers on, read from its kempo-config.json.
+
+  An extension serves a folder of its package at an address under its scope: with the scope `products`,
+  `public/index.page.html` is `/products/` and `public/api/products/GET.js` is `/products/api/products`.
+  It can claim more than one scope, each serving its own folder:
+
+    "public-scope": "products",                              // shorthand for "products": "public"
+    "public-scopes": { "categories": "public-categories" }   // /categories/ serves public-categories/
+
+  `aliases` give pages under a scope a second, shorter address (see aliases.js). Every scope and every
+  alias address is a *claim*: no two enabled extensions may claim the same address, or one inside the
+  other, because the router can only give an address to one of them (see claims.js).
+*/
+
+const NAME = /^[a-z0-9][a-z0-9_-]*$/;
+
+/* What kempo itself serves at the top level of the site. */
+export const RESERVED_SCOPES = ['admin', 'api', 'kempo', 'kempo-css', 'kempo-ui', 'monaco-editor'];
+
+const cleanDir = dir => String(dir).replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+
+const badDir = dir => !dir || dir.startsWith('/') || /^[a-z]:/i.test(dir) || dir.split('/').some(part => part === '..' || part === '');
+
+/*
+  The scopes an extension declares, each with the folder of its package it serves: [error, [{ scope, dir }]].
+  An extension with no scope gets an empty list. A bad name, a reserved one, a folder that leaves the
+  package, or the same scope pointed at two folders is an error.
+*/
+export const normalizeScopes = kempo => {
+  const found = new Map();
+
+  const add = (scope, folder) => {
+    if(typeof scope !== 'string' || !NAME.test(scope)){
+      return { code: 400, msg: `Scope "${scope}" must be lowercase letters, numbers, dashes or underscores, such as "products"` };
+    }
+    if(RESERVED_SCOPES.includes(scope)){
+      return { code: 400, msg: `Scope "${scope}" is used by kempo itself` };
+    }
+    const dir = cleanDir(folder);
+    if(typeof folder !== 'string' || badDir(dir)){
+      return { code: 400, msg: `The folder for scope "${scope}" must be a folder inside the package, such as "public"` };
+    }
+    if(found.has(scope) && found.get(scope) !== dir){
+      return { code: 400, msg: `Scope "${scope}" is given two different folders` };
+    }
+    found.set(scope, dir);
+    return null;
+  };
+
+  const single = kempo?.['public-scope'];
+  if(single !== undefined && single !== null && single !== ''){
+    const error = add(single, 'public');
+    if(error) return [error, null];
+  }
+
+  const several = kempo?.['public-scopes'];
+  if(several !== undefined && several !== null){
+    if(typeof several !== 'object' || Array.isArray(several)){
+      return [{ code: 400, msg: 'public-scopes must be an object of scope to folder' }, null];
+    }
+    for(const [scope, folder] of Object.entries(several)){
+      const error = add(scope, folder);
+      if(error) return [error, null];
+    }
+  }
+
+  return [null, [...found].map(([scope, dir]) => ({ scope, dir }))];
+};
+
+/* Just the scope names, for what only needs to know them (an alias must point inside one). */
+export const scopeNames = kempo => (normalizeScopes(kempo)[1] ?? []).map(({ scope }) => scope);

package/server/utils/extensions/uninstallExtensionTree.js

@@ -1,5 +1,5 @@
 import db from '../../db/index.js';
-import { extension, hook, permission, setting, group, groupPermission, userGroup, dashboardWidget } from '../../db/schema.js';
+import { extension, hook, permission, setting, group, groupPermission, userGroup, dashboardWidget, scheduledJob } from '../../db/schema.js';
 import { eq, inArray, like } from 'drizzle-orm';
 import { join } from 'path';
 import { pathToFileURL } from 'url';
@@ -105,6 +105,7 @@ const uninstallOne = async ({ name, purgeData = false }) => {
   try {
     await db.delete(hook).where(eq(hook.owner, name));
     await db.delete(dashboardWidget).where(eq(dashboardWidget.owner, name));
+    await db.delete(scheduledJob).where(eq(scheduledJob.owner, name)).catch(() => {});
     await db.delete(extension).where(eq(extension.name, name));
   } catch(error) {
     return [{ code: 500, msg: 'Failed to remove extension' }, null];

package/server/utils/extensions/updateExtension.js

@@ -9,10 +9,14 @@ 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 { normalizeAliases } from './aliases.js';
+import { normalizeScopes, scopeNames } from './scopes.js';
+import checkClaims from './checkClaims.js';
 
 const requireFromProject = createRequire(join(process.cwd(), 'package.json'));
 
@@ -56,6 +60,27 @@ export default async ({ name, version = 'latest' }) => {
     return [{ code: 404, msg: `Updated package "${name}" not found` }, null];
   }
 
+  /*
+    The new version may claim addresses the old one did not. If it is on and another extension has one
+    of them, put the old version back before anything else changes: leaving the new one would break
+    one of the two, silently.
+  */
+  const [scopesError] = normalizeScopes(newKempo);
+  const [aliasesError] = scopesError ? [null] : normalizeAliases(newKempo.aliases, scopeNames(newKempo));
+  const [claimsError] = scopesError || aliasesError || !oldRecord.enabled
+    ? [null]
+    : await checkClaims({ names: [name], verb: 'update', kempo: { [name]: newKempo } });
+  const refusal = scopesError || aliasesError || claimsError;
+  if(refusal){
+    let msg = refusal.msg;
+    try {
+      if(oldVersion) execSync(`npm install ${name}@${oldVersion}`, { cwd: process.cwd(), stdio: 'pipe' });
+    } catch {
+      msg += ` The previous version could not be put back automatically: run npm install ${name}@${oldVersion}.`;
+    }
+    return [{ ...refusal, msg }, null];
+  }
+
   /*
     Create any new tables from schema
   */
@@ -161,6 +186,16 @@ export default async ({ name, version = 'latest' }) => {
     }
   }
 
+  /*
+    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({

package/server/utils/global-content/createGlobalContent.js

@@ -2,25 +2,10 @@ import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
 import crypto from 'crypto';
-import { GLOBAL_FILE, parseEntries } from './helpers.js';
+import { GLOBAL_FILE, parseEntries, serializeEntries } from './helpers.js';
 import triggerHook from '../hooks/triggerHook.js';
 
-const serializeEntries = entries => entries.map(e => {
-  const attrs = [
-    `id="${e.id}"`,
-    `name="${e.name}"`,
-    `owner="${e.owner}"`,
-    `author="${e.author}"`,
-    `created="${e.createdAt}"`,
-    `updated="${e.updatedAt}"`,
-    `locked="${e.locked}"`,
-    `location="${e.location}"`,
-    `priority="${e.priority}"`
-  ].join(' ');
-  return `<content ${attrs}>\n${e.markup}\n</content>`;
-}).join('\n');
-
-export default async ({ rootDir, name, location, priority, author, owner = 'custom' }) => {
+export default async ({ rootDir, name, location, priority, author, owner = 'custom', markup = '' }) => {
   if(!rootDir){
     return [{ code: 400, msg: 'Root directory is required' }, null];
   }
@@ -45,11 +30,16 @@ export default async ({ rootDir, name, location, priority, author, owner = 'cust
     owner,
     author: author || '',
     locked: false,
+    menu: '',
+    menuLocations: null,
+    menuCopyOf: '',
+    navItem: '',
+    extra: {},
     location,
     priority: parseInt(priority || '0', 10),
     createdAt: now,
     updatedAt: now,
-    markup: ''
+    markup
   };
 
   entries.push(entry);

package/server/utils/global-content/deleteGlobalContent.js

@@ -1,24 +1,9 @@
 import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
-import { GLOBAL_FILE, parseEntries } from './helpers.js';
+import { GLOBAL_FILE, parseEntries, serializeEntries } from './helpers.js';
 import triggerHook from '../hooks/triggerHook.js';
 
-const serializeEntries = entries => entries.map(e => {
-  const attrs = [
-    `id="${e.id}"`,
-    `name="${e.name}"`,
-    `owner="${e.owner}"`,
-    `author="${e.author}"`,
-    `created="${e.createdAt}"`,
-    `updated="${e.updatedAt}"`,
-    `locked="${e.locked}"`,
-    `location="${e.location}"`,
-    `priority="${e.priority}"`
-  ].join(' ');
-  return `<content ${attrs}>\n${e.markup}\n</content>`;
-}).join('\n');
-
 export default async ({ rootDir, ids }) => {
   if(!rootDir){
     return [{ code: 400, msg: 'Root directory is required' }, null];

package/server/utils/global-content/disableGlobalContent.js

@@ -1,22 +1,7 @@
 import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
-import { GLOBAL_FILE, GLOBAL_DISABLED_FILE, parseEntries } from './helpers.js';
-
-const serializeEntries = entries => entries.map(e => {
-  const attrs = [
-    `id="${e.id}"`,
-    `name="${e.name}"`,
-    `owner="${e.owner}"`,
-    `author="${e.author}"`,
-    `created="${e.createdAt}"`,
-    `updated="${e.updatedAt}"`,
-    `locked="${e.locked}"`,
-    `location="${e.location}"`,
-    `priority="${e.priority}"`
-  ].join(' ');
-  return `<content ${attrs}>\n${e.markup}\n</content>`;
-}).join('\n');
+import { GLOBAL_FILE, GLOBAL_DISABLED_FILE, parseEntries, serializeEntries } from './helpers.js';
 
 export default async ({ rootDir, id }) => {
   if(!rootDir){

package/server/utils/global-content/enableGlobalContent.js

@@ -1,22 +1,7 @@
 import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
-import { GLOBAL_FILE, GLOBAL_DISABLED_FILE, parseEntries } from './helpers.js';
-
-const serializeEntries = entries => entries.map(e => {
-  const attrs = [
-    `id="${e.id}"`,
-    `name="${e.name}"`,
-    `owner="${e.owner}"`,
-    `author="${e.author}"`,
-    `created="${e.createdAt}"`,
-    `updated="${e.updatedAt}"`,
-    `locked="${e.locked}"`,
-    `location="${e.location}"`,
-    `priority="${e.priority}"`
-  ].join(' ');
-  return `<content ${attrs}>\n${e.markup}\n</content>`;
-}).join('\n');
+import { GLOBAL_FILE, GLOBAL_DISABLED_FILE, parseEntries, serializeEntries } from './helpers.js';
 
 export default async ({ rootDir, id }) => {
   if(!rootDir){

package/server/utils/global-content/helpers.js

@@ -1,10 +1,19 @@
-import { readFile } from 'fs/promises';
-import { join } from 'path';
-import { existsSync } from 'fs';
-
 const GLOBAL_FILE = 'kempo-global.global.html';
 const GLOBAL_DISABLED_FILE = 'kempo-global.global-disabled.html';
 
+/*
+  A quote or angle bracket inside an attribute would end the tag early, so they are written as
+  entities and read back.
+*/
+const escapeAttr = value => String(value ?? '').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const unescapeAttr = value => value.replace(/&quot;/g, '"').replace(/&lt;/g, '<').replace(/&gt;/g, '>');
+
+const KNOWN_ATTRIBUTES = ['id', 'name', 'owner', 'author', 'locked', 'location', 'priority', 'created', 'updated', 'menu', 'menu-locations', 'menu-copy', 'menu-nav-item'];
+
+/*
+  Attributes this code does not know about are kept in `extra` and written back unchanged, so a
+  marker added by hand or by a newer version survives a save instead of being silently dropped.
+*/
 const parseEntries = raw => {
   const entries = [];
   const regex = /<content\s([^>]*)>([\s\S]*?)<\/content>/g;
@@ -13,21 +22,46 @@ const parseEntries = raw => {
     const attrs = {};
     const attrRegex = /(\w[\w-]*)="([^"]*)"/g;
     let a;
-    while((a = attrRegex.exec(match[1])) !== null) attrs[a[1]] = a[2];
+    while((a = attrRegex.exec(match[1])) !== null) attrs[a[1]] = unescapeAttr(a[2]);
     entries.push({
       id: attrs.id || '',
       name: attrs.name || '',
       owner: attrs.owner || 'custom',
       author: attrs.author || '',
       locked: attrs.locked === 'true',
+      menu: attrs.menu || '',
+      menuLocations: attrs['menu-locations'] === undefined ? null : attrs['menu-locations'].split(',').map(l => l.trim()).filter(Boolean),
+      menuCopyOf: attrs['menu-copy'] || '',
+      navItem: attrs['menu-nav-item'] || '',
       location: attrs.location || 'default',
       priority: parseInt(attrs.priority || '0', 10),
       createdAt: attrs.created || '',
       updatedAt: attrs.updated || '',
+      extra: Object.fromEntries(Object.entries(attrs).filter(([key]) => !KNOWN_ATTRIBUTES.includes(key))),
       markup: match[2].trim()
     });
   }
   return entries;
 };
 
-export { GLOBAL_FILE, GLOBAL_DISABLED_FILE, parseEntries };
+const serializeEntries = entries => entries.map(e => {
+  const attrs = [
+    `id="${e.id}"`,
+    `name="${escapeAttr(e.name)}"`,
+    `owner="${e.owner}"`,
+    `author="${escapeAttr(e.author)}"`,
+    `created="${e.createdAt}"`,
+    `updated="${e.updatedAt}"`,
+    `locked="${e.locked}"`,
+    `location="${e.location}"`,
+    `priority="${e.priority}"`,
+    ...(e.menu ? [`menu="${e.menu}"`] : []),
+    ...(e.menuLocations ? [`menu-locations="${e.menuLocations.join(',')}"`] : []),
+    ...(e.menuCopyOf ? [`menu-copy="${e.menuCopyOf}"`] : []),
+    ...(e.navItem ? [`menu-nav-item="${e.navItem}"`] : []),
+    ...Object.entries(e.extra || {}).map(([key, value]) => `${key}="${escapeAttr(value)}"`)
+  ].join(' ');
+  return `<content ${attrs}>\n${e.markup}\n</content>`;
+}).join('\n');
+
+export { GLOBAL_FILE, GLOBAL_DISABLED_FILE, parseEntries, serializeEntries };

package/server/utils/global-content/listGlobalContent.js

@@ -3,7 +3,7 @@ import { join } from 'path';
 import { existsSync } from 'fs';
 import { GLOBAL_FILE, GLOBAL_DISABLED_FILE, parseEntries } from './helpers.js';
 
-export default async ({ rootDir }) => {
+export default async ({ rootDir, includeMenu = true }) => {
   if(!rootDir){
     return [{ code: 400, msg: 'Root directory is required' }, null];
   }
@@ -19,6 +19,6 @@ export default async ({ rootDir }) => {
     ? parseEntries(await readFile(disabledPath, 'utf-8')).map(e => ({ ...e, disabled: true }))
     : [];
 
-  const entries = [...activeEntries, ...disabledEntries];
+  const entries = [...activeEntries, ...disabledEntries].filter(e => includeMenu || !e.menu);
   return [null, { entries, total: entries.length }];
 };

package/server/utils/global-content/setGlobalContentLocked.js

@@ -1,22 +1,7 @@
 import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
-import { GLOBAL_FILE, parseEntries } from './helpers.js';
-
-const serializeEntries = entries => entries.map(e => {
-  const attrs = [
-    `id="${e.id}"`,
-    `name="${e.name}"`,
-    `owner="${e.owner}"`,
-    `author="${e.author}"`,
-    `created="${e.createdAt}"`,
-    `updated="${e.updatedAt}"`,
-    `locked="${e.locked}"`,
-    `location="${e.location}"`,
-    `priority="${e.priority}"`
-  ].join(' ');
-  return `<content ${attrs}>\n${e.markup}\n</content>`;
-}).join('\n');
+import { GLOBAL_FILE, parseEntries, serializeEntries } from './helpers.js';
 
 export default async ({ rootDir, id, locked }) => {
   if(!rootDir) return [{ code: 400, msg: 'Root directory is required' }, null];

package/server/utils/global-content/updateGlobalContent.js

@@ -1,24 +1,9 @@
 import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
-import { GLOBAL_FILE, parseEntries } from './helpers.js';
+import { GLOBAL_FILE, parseEntries, serializeEntries } from './helpers.js';
 import triggerHook from '../hooks/triggerHook.js';
 
-const serializeEntries = entries => entries.map(e => {
-  const attrs = [
-    `id="${e.id}"`,
-    `name="${e.name}"`,
-    `owner="${e.owner}"`,
-    `author="${e.author}"`,
-    `created="${e.createdAt}"`,
-    `updated="${e.updatedAt}"`,
-    `locked="${e.locked}"`,
-    `location="${e.location}"`,
-    `priority="${e.priority}"`
-  ].join(' ');
-  return `<content ${attrs}>\n${e.markup}\n</content>`;
-}).join('\n');
-
 export default async ({ rootDir, id, name, location, priority, markup }) => {
   if(!rootDir){
     return [{ code: 400, msg: 'Root directory is required' }, null];

package/server/utils/menus/adoptMenuItem.js

@@ -0,0 +1,58 @@
+import { readStores, writeStores, menuHome, isMenuDefinition } from './store.js';
+import { parseLink } from './markup.js';
+import saveMenu from './saveMenu.js';
+import triggerHook from '../hooks/triggerHook.js';
+
+/*
+  Moves an existing single link into a menu so it is managed on the Menus page. Only a single link
+  qualifies: anything else would lose what it is made of when the page rewrites it.
+
+  Without a `menuId` it goes into the menu already shown in the link's location; if there is none, a
+  menu named `menuName` is made and shown there, so the link stays exactly where it was on the site.
+*/
+export default async ({ rootDir, id, menuId, menuName, extensionDirs }) => {
+  if(!rootDir){
+    return [{ code: 400, msg: 'Root directory is required' }, null];
+  }
+  if(!id){
+    return [{ code: 400, msg: 'Global content ID is required' }, null];
+  }
+
+  let stores = await readStores(rootDir);
+  const entry = stores.active.find(e => e.id === id && !e.menu);
+  if(!entry){
+    return [{ code: 404, msg: 'Global content not found' }, null];
+  }
+  if(entry.owner !== 'custom'){
+    return [{ code: 403, msg: 'This belongs to an extension' }, null];
+  }
+  if(!parseLink(entry.markup)){
+    return [{ code: 400, msg: 'Only a single link can be managed as a menu item' }, null];
+  }
+
+  let target = menuId
+    ? stores.active.find(e => e.id === menuId && isMenuDefinition(e))
+    : stores.active.find(e => isMenuDefinition(e) && e.menuLocations.includes(entry.location));
+  if(menuId && !target){
+    return [{ code: 404, msg: 'Menu not found' }, null];
+  }
+
+  if(!target){
+    const [error, created] = await saveMenu({ rootDir, name: menuName || entry.location, extensionDirs });
+    if(error){
+      return [error, null];
+    }
+    stores = await readStores(rootDir);
+    target = stores.active.find(e => e.id === created.id);
+    target.menuLocations = [entry.location];
+  }
+
+  const live = stores.active.find(e => e.id === id);
+  live.menu = target.id;
+  live.location = menuHome(target.id);
+  live.updatedAt = new Date().toISOString();
+  await writeStores(rootDir, stores, extensionDirs);
+  await triggerHook('globalContent:updated', { id, updatedAt: live.updatedAt });
+
+  return [null, { id, menuId: target.id }];
+};

package/server/utils/menus/assignMenuLocation.js

@@ -0,0 +1,47 @@
+import { readStores, writeStores, isMenuDefinition } from './store.js';
+import findMenuLocations from './findMenuLocations.js';
+import triggerHook from '../hooks/triggerHook.js';
+
+/*
+  Chooses the menu shown in a location, or none when `menuId` is empty. A location shows one menu, so
+  choosing one takes the location from whichever menu had it; a menu can be chosen for several.
+  Only a place the theme marks as a menu can be newly assigned, so a typo cannot silently show nothing.
+*/
+export default async ({ rootDir, location, menuId, extensionDirs }) => {
+  if(!rootDir){
+    return [{ code: 400, msg: 'Root directory is required' }, null];
+  }
+  if(!location){
+    return [{ code: 400, msg: 'Location is required' }, null];
+  }
+
+  const stores = await readStores(rootDir);
+  const definitions = stores.active.filter(isMenuDefinition);
+  const target = menuId ? definitions.find(d => d.id === menuId) : null;
+  if(menuId && !target){
+    return [{ code: 404, msg: 'Menu not found' }, null];
+  }
+
+  if(target){
+    const [, declared] = await findMenuLocations({ rootDir });
+    if(!target.menuLocations.includes(location) && !declared.some(l => l.location === location)){
+      return [{ code: 400, msg: 'That place is not a menu in the theme' }, null];
+    }
+  }
+
+  const now = new Date().toISOString();
+  for(const definition of definitions){
+    if(!definition.menuLocations.includes(location)) continue;
+    definition.menuLocations = definition.menuLocations.filter(l => l !== location);
+    definition.updatedAt = now;
+  }
+  if(target){
+    target.menuLocations = [...target.menuLocations, location];
+    target.updatedAt = now;
+  }
+
+  await writeStores(rootDir, stores, extensionDirs);
+  await triggerHook('globalContent:updated', { id: target?.id ?? '', updatedAt: now });
+
+  return [null, { location, menuId: target?.id ?? null }];
+};