nextpluggable 0.0.0-stage → 0.1.0

package/dist/core/installer.js

@@ -0,0 +1,340 @@
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { checkPagePath, defaultConfig, isStaticPath, validateBuild, validateSettings, ManifestError } from '@nextpluggable/plugin/manifest';
+import { decrypt, encrypt, isEncrypted, sha256Hex } from '../crypto.js';
+import { HttpError } from '../errors.js';
+import { globals } from '../globals.js';
+import { parseGitHubUrl } from '../sources/github.js';
+import { decodeText, joinPath, loadCatalog, readerFor } from '../sources/reader.js';
+import { effectivePaths, pathProblem } from './routes.js';
+import { evaluateServer, loadServer, pluginContext } from './runtime.js';
+import { invalidateInstalledPlugins } from './state.js';
+import { deleteCatalog, deletePluginData, getInstalls, getSources, pruneFiles, putFile, saveCatalog, saveInstalls, saveSources, } from './store.js';
+const MAX_BYTES = { client: 3_000_000, server: 5_000_000, style: 1_000_000 };
+const KINDS = ['client', 'server', 'style'];
+const reservedPaths = (cfg) => [cfg.dashboardPath, cfg.apiPath, '/_next', '/api'];
+/** True while a required setting has no value — the plugin stays paused until the owner fills it in. */
+export function needsSetup(manifest, config) {
+    return (manifest.settings ?? []).some((f) => f.required && (config[f.key] === undefined || config[f.key] === ''));
+}
+// ---------------------------------------------------------------- sources
+export async function addSource(cfg, input) {
+    const url = typeof input.url === 'string' ? input.url.trim() : '';
+    const token = typeof input.token === 'string' ? input.token.trim() : '';
+    if (!url)
+        throw new HttpError(400, 'Paste the address of the GitHub repository that holds the plugins.');
+    const sources = await getSources(cfg.storage);
+    const id = `s${randomBytes(5).toString('hex')}`;
+    const addedAt = new Date().toISOString();
+    let record;
+    const gh = parseGitHubUrl(url);
+    if (gh) {
+        const same = sources.find((s) => s.github &&
+            s.github.owner.toLowerCase() === gh.owner.toLowerCase() &&
+            s.github.repo.toLowerCase() === gh.repo.toLowerCase() &&
+            (s.github.dir ?? '') === (gh.dir ?? '') &&
+            (s.github.ref ?? '') === (gh.ref ?? ''));
+        if (same)
+            throw new HttpError(409, `${same.label} is already connected.`);
+        record = {
+            id,
+            type: 'github',
+            label: `${gh.owner}/${gh.repo}${gh.dir ? `/${gh.dir}` : ''}`,
+            addedAt,
+            github: { ...gh, ...(token ? { token: encrypt(cfg.secret, token) } : {}) },
+        };
+    }
+    else if (cfg.allowLocalSources && /^(file:|\/|\.\.?\/|[A-Za-z]:[\\/])/.test(url)) {
+        const dir = path.resolve(/* turbopackIgnore: true */ url.replace(/^file:(\/\/)?/, ''));
+        if (sources.some((s) => s.local?.dir === dir))
+            throw new HttpError(409, 'That folder is already connected.');
+        record = { id, type: 'local', label: path.basename(dir) || dir, addedAt, local: { dir } };
+    }
+    else {
+        throw new HttpError(400, 'That does not look like a GitHub repository address. It should look like https://github.com/owner/repository.');
+    }
+    // Reading the catalog first proves the address and token work before anything is saved.
+    const { reader, baseDir } = readerFor(cfg, record);
+    const catalog = await loadCatalog(record, reader, baseDir);
+    await saveCatalog(cfg.storage, catalog);
+    await saveSources(cfg.storage, [...sources, record]);
+    return record;
+}
+export async function refreshSource(cfg, source) {
+    const { reader, baseDir } = readerFor(cfg, source);
+    const catalog = await loadCatalog(source, reader, baseDir);
+    await saveCatalog(cfg.storage, catalog);
+    return catalog;
+}
+/** Refresh every source; one failing source does not stop the others. */
+export async function refreshAllSources(cfg) {
+    const failures = [];
+    await Promise.all((await getSources(cfg.storage)).map((source) => refreshSource(cfg, source).catch((e) => {
+        failures.push({ label: source.label, message: e instanceof HttpError ? e.message : 'Something went wrong reading this source.' });
+        if (!(e instanceof HttpError))
+            console.error('[nextpluggable] refresh failed', e);
+    })));
+    return failures;
+}
+export async function removeSource(cfg, sourceId) {
+    const sources = await getSources(cfg.storage);
+    if (!sources.some((s) => s.id === sourceId))
+        throw new HttpError(404, 'That source is no longer connected.');
+    await saveSources(cfg.storage, sources.filter((s) => s.id !== sourceId));
+    await deleteCatalog(cfg.storage, sourceId);
+}
+// ---------------------------------------------------------------- install / update
+async function fetchBuild(cfg, source, pluginPath) {
+    const { reader, baseDir } = readerFor(cfg, source);
+    const revision = await reader.resolveRevision();
+    const dir = joinPath(baseDir, pluginPath);
+    const buildBytes = await reader.read(joinPath(dir, 'dist/build.json'), revision);
+    if (!buildBytes)
+        throw new HttpError(404, `That plugin is no longer available in ${source.label}.`);
+    let build;
+    try {
+        build = validateBuild(JSON.parse(decodeText(buildBytes)));
+    }
+    catch (e) {
+        throw new HttpError(422, `This plugin cannot be installed because its package is not valid: ${e instanceof ManifestError ? e.problems.join('; ') : 'unreadable build file'}.`);
+    }
+    const files = {};
+    await Promise.all(KINDS.map(async (kind) => {
+        const entry = build.files[kind];
+        if (!entry)
+            return;
+        if (entry.bytes > MAX_BYTES[kind])
+            throw new HttpError(422, `This plugin is too large to install (${kind} bundle is ${(entry.bytes / 1e6).toFixed(1)} MB).`);
+        const bytes = await reader.read(joinPath(dir, entry.path), revision);
+        if (!bytes)
+            throw new HttpError(422, `This plugin is incomplete: ${entry.path} is missing from ${source.label}.`);
+        // Integrity: what we store must be byte-for-byte what the plugin's build recorded.
+        if (sha256Hex(bytes) !== entry.sha256)
+            throw new HttpError(422, `This plugin failed its integrity check (${entry.path} does not match its recorded fingerprint). Ask the plugin author to rebuild it.`);
+        files[kind] = { meta: { sha256: entry.sha256, bytes: bytes.byteLength }, content: decodeText(bytes) };
+    }));
+    return { build, buildHash: sha256Hex(buildBytes), revision, files };
+}
+function carryConfig(manifest, previous) {
+    const config = { ...defaultConfig(manifest) };
+    if (!previous)
+        return config;
+    const plain = {};
+    for (const f of manifest.settings ?? []) {
+        const v = previous[f.key];
+        if (v === undefined)
+            continue;
+        if (f.type === 'secret') {
+            if (isEncrypted(v))
+                config[f.key] = v;
+        }
+        else
+            plain[f.key] = v;
+    }
+    // Keep earlier answers that are still valid under the new version's rules.
+    const { values } = validateSettings({ ...manifest, settings: (manifest.settings ?? []).filter((f) => f.type !== 'secret' && f.key in plain) }, plain);
+    return { ...config, ...values };
+}
+async function install(cfg, source, pluginPath, existing) {
+    const fetched = await fetchBuild(cfg, source, pluginPath);
+    const { manifest } = fetched.build;
+    const installs = await getInstalls(cfg.storage);
+    if (existing) {
+        if (manifest.id !== existing.id)
+            throw new HttpError(409, 'The plugin at this location now has a different identity and cannot be used as an update.');
+    }
+    else if (installs[manifest.id]) {
+        throw new HttpError(409, `${installs[manifest.id].manifest.name} is already installed.`);
+    }
+    // Page addresses: keep the owner's choices where the page still exists.
+    const paths = {};
+    for (const page of manifest.pages ?? []) {
+        const chosen = existing?.paths[page.id];
+        if (chosen && page.configurablePath !== false && isStaticPath(page.path))
+            paths[page.id] = chosen;
+    }
+    const others = { ...installs };
+    delete others[manifest.id];
+    const draft = { id: manifest.id, manifest, paths };
+    for (const page of manifest.pages ?? []) {
+        const problem = pathProblem({ ...others, [manifest.id]: draft }, manifest.id, page.id, effectivePaths(draft)[page.id], reservedPaths(cfg));
+        if (problem)
+            throw new HttpError(409, `${problem} Change that page's address first, then try again.`);
+    }
+    const config = carryConfig(manifest, existing?.config);
+    const now = new Date().toISOString();
+    const files = {};
+    for (const kind of KINDS) {
+        const f = fetched.files[kind];
+        if (!f)
+            continue;
+        await putFile(cfg.storage, manifest.id, kind, f.meta.sha256, f.content);
+        files[kind] = f.meta;
+    }
+    const incomplete = needsSetup(manifest, config);
+    const record = {
+        id: manifest.id,
+        manifest,
+        icon: fetched.build.icon,
+        buildHash: fetched.buildHash,
+        source: { id: source.id, label: source.label, path: pluginPath, revision: fetched.revision },
+        files,
+        previousFiles: existing?.files,
+        enabled: existing ? existing.enabled && !incomplete : !incomplete,
+        config,
+        paths,
+        installedAt: existing?.installedAt ?? now,
+        updatedAt: now,
+    };
+    try {
+        if (fetched.files.server) {
+            const server = evaluateServer(manifest.id, fetched.files.server.content);
+            if (!existing)
+                await server.onInstall?.(pluginContext(cfg, record));
+        }
+    }
+    catch (e) {
+        console.error(`[nextpluggable] Plugin "${manifest.id}" failed to start:`, e);
+        await pruneFiles(cfg.storage, manifest.id, existing ? [existing.files, existing.previousFiles ?? {}] : []);
+        throw new HttpError(422, `${manifest.name} could not be ${existing ? 'updated' : 'installed'} because it failed to start. Nothing was changed.`);
+    }
+    await saveInstalls(cfg.storage, { ...installs, [manifest.id]: record });
+    await pruneFiles(cfg.storage, manifest.id, [record.files, record.previousFiles ?? {}]);
+    invalidateInstalledPlugins(cfg);
+    return record;
+}
+export async function installPlugin(cfg, input) {
+    const source = (await getSources(cfg.storage)).find((s) => s.id === input.sourceId);
+    if (!source)
+        throw new HttpError(404, 'That source is no longer connected.');
+    const pluginPath = typeof input.path === 'string' ? input.path : '';
+    if (pluginPath.split('/').some((p) => p === '..'))
+        throw new HttpError(400, 'Invalid plugin location.');
+    return install(cfg, source, pluginPath, undefined);
+}
+export async function updatePlugin(cfg, pluginId) {
+    const all = await getInstalls(cfg.storage);
+    const existing = Object.hasOwn(all, pluginId) ? all[pluginId] : undefined;
+    if (!existing)
+        throw new HttpError(404, 'That plugin is not installed.');
+    const source = (await getSources(cfg.storage)).find((s) => s.id === existing.source.id);
+    if (!source)
+        throw new HttpError(409, `${existing.manifest.name} came from a source that is no longer connected, so it cannot be updated. Connect ${existing.source.label} again first.`);
+    const record = await install(cfg, source, existing.source.path, existing);
+    await refreshSource(cfg, source).catch(() => { });
+    return record;
+}
+export async function changePlugin(cfg, pluginId, patch) {
+    const installs = await getInstalls(cfg.storage);
+    const current = Object.hasOwn(installs, pluginId) ? installs[pluginId] : undefined;
+    if (!current)
+        throw new HttpError(404, 'That plugin is not installed.');
+    const next = { ...current, config: { ...current.config }, paths: { ...current.paths } };
+    const { manifest } = current;
+    // Every problem is collected and reported together, so the owner fixes them in one go.
+    const errors = {};
+    if (patch.config !== undefined) {
+        if (typeof patch.config !== 'object' || patch.config === null)
+            throw new HttpError(400, 'Invalid settings.');
+        const incoming = patch.config;
+        const candidate = {};
+        for (const f of manifest.settings ?? []) {
+            if (Object.hasOwn(incoming, f.key))
+                candidate[f.key] = incoming[f.key];
+            else if (f.type === 'secret') {
+                // Secrets are write-only in the dashboard: leaving the field untouched keeps the stored value.
+                const stored = current.config[f.key];
+                if (isEncrypted(stored))
+                    candidate[f.key] = decrypt(cfg.secret, stored) ?? undefined;
+            }
+            else
+                candidate[f.key] = current.config[f.key];
+        }
+        const checked = validateSettings(manifest, candidate);
+        Object.assign(errors, checked.errors);
+        for (const f of manifest.settings ?? []) {
+            const v = checked.values[f.key];
+            if (f.type === 'secret' && typeof v === 'string')
+                checked.values[f.key] = encrypt(cfg.secret, v);
+        }
+        next.config = checked.values;
+    }
+    if (patch.paths !== undefined) {
+        if (typeof patch.paths !== 'object' || patch.paths === null)
+            throw new HttpError(400, 'Invalid page addresses.');
+        for (const [pageId, raw] of Object.entries(patch.paths)) {
+            const page = manifest.pages?.find((p) => p.id === pageId);
+            if (!page)
+                continue;
+            const field = `path:${pageId}`;
+            let value = typeof raw === 'string' ? raw.trim() : '';
+            if (value && !value.startsWith('/'))
+                value = `/${value}`;
+            value = value.replace(/\/+$/, '').toLowerCase();
+            if (!value || value === page.path) {
+                delete next.paths[pageId];
+                continue;
+            }
+            if (value === effectivePaths(current)[pageId])
+                continue;
+            if (page.configurablePath === false || !isStaticPath(page.path)) {
+                errors[field] = 'The address of this page cannot be changed.';
+                continue;
+            }
+            const problem = checkPagePath(value);
+            if (problem || !isStaticPath(value)) {
+                errors[field] = `The address ${problem ?? 'cannot contain ":" or "*"'}. Use something like /loan-calculator.`;
+                continue;
+            }
+            next.paths[pageId] = value;
+        }
+        for (const page of manifest.pages ?? []) {
+            const field = `path:${page.id}`;
+            if (errors[field])
+                continue;
+            const problem = pathProblem({ ...installs, [pluginId]: next }, pluginId, page.id, effectivePaths(next)[page.id], reservedPaths(cfg));
+            if (problem)
+                errors[field] = problem;
+        }
+    }
+    if (Object.keys(errors).length)
+        throw new HttpError(422, 'Some settings need your attention.', errors);
+    if (patch.enabled !== undefined) {
+        if (typeof patch.enabled !== 'boolean')
+            throw new HttpError(400, 'Invalid request.');
+        next.enabled = patch.enabled;
+    }
+    if (next.enabled && needsSetup(manifest, next.config)) {
+        if (patch.enabled === true)
+            throw new HttpError(422, `${manifest.name} needs a few settings filled in before it can be turned on.`);
+        next.enabled = false;
+    }
+    next.updatedAt = new Date().toISOString();
+    await saveInstalls(cfg.storage, { ...installs, [pluginId]: next });
+    invalidateInstalledPlugins(cfg);
+    return next;
+}
+export async function uninstallPlugin(cfg, pluginId, options = {}) {
+    const installs = await getInstalls(cfg.storage);
+    const current = Object.hasOwn(installs, pluginId) ? installs[pluginId] : undefined;
+    if (!current)
+        throw new HttpError(404, 'That plugin is not installed.');
+    try {
+        await (await loadServer(cfg, current))?.onUninstall?.(pluginContext(cfg, current));
+    }
+    catch (e) {
+        console.error(`[nextpluggable] Plugin "${pluginId}" failed in its uninstall step (continuing):`, e);
+    }
+    const rest = { ...installs };
+    delete rest[pluginId];
+    await saveInstalls(cfg.storage, rest);
+    invalidateInstalledPlugins(cfg);
+    await pruneFiles(cfg.storage, pluginId, []);
+    if (options.deleteData)
+        await deletePluginData(cfg.storage, pluginId);
+    const g = globals();
+    for (const cache of [g.serverModules, g.ssrCode])
+        for (const k of cache.keys())
+            if (k.startsWith(`${pluginId}@`))
+                cache.delete(k);
+}

package/dist/core/routes.d.ts

@@ -0,0 +1,20 @@
+import type { PluginPage } from '@nextpluggable/plugin/manifest';
+import type { InstallRecord, Installs } from './types.js';
+export declare function normalizePathname(pathname: string): string;
+/** Match a pathname against a pattern such as `/shop/:slug` or `/docs/*`. Returns params, or null. */
+export declare function matchPattern(pattern: string, pathname: string): Record<string, string> | null;
+/** The address each page of a plugin is served at (owner's choice, else the plugin's default). */
+export declare function effectivePaths(install: InstallRecord): Record<string, string>;
+export interface PageMatch {
+    install: InstallRecord;
+    page: PluginPage;
+    /** The pattern that matched. */
+    pattern: string;
+    params: Record<string, string>;
+}
+export declare function findPage(installs: Installs, pathname: string): PageMatch | null;
+/**
+ * Check a page address before it is saved. Returns a sentence for the site
+ * owner when the address cannot be used, or null when it is fine.
+ */
+export declare function pathProblem(installs: Installs, pluginId: string, pageId: string, pattern: string, reserved: string[]): string | null;

package/dist/core/routes.js

@@ -0,0 +1,95 @@
+import { isStaticPath } from '@nextpluggable/plugin/manifest';
+export function normalizePathname(pathname) {
+    const p = `/${pathname}`.replace(/\/{2,}/g, '/');
+    return p.length > 1 ? p.replace(/\/+$/, '') : p;
+}
+const safeDecode = (s) => {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+};
+/** Match a pathname against a pattern such as `/shop/:slug` or `/docs/*`. Returns params, or null. */
+export function matchPattern(pattern, pathname) {
+    const want = pattern === '/' ? [] : pattern.slice(1).split('/');
+    const got = pathname === '/' ? [] : pathname.slice(1).split('/');
+    const params = {};
+    for (let i = 0; i < want.length; i++) {
+        const w = want[i];
+        if (w === '*') {
+            params['*'] = got.slice(i).map(safeDecode).join('/');
+            return params;
+        }
+        const g = got[i];
+        if (g === undefined || g === '')
+            return null;
+        if (w.startsWith(':'))
+            params[w.slice(1)] = safeDecode(g);
+        else if (w !== g && w !== safeDecode(g))
+            return null;
+    }
+    return got.length === want.length ? params : null;
+}
+/** Higher wins: fully static paths, then more literal segments, wildcards last. */
+function specificity(pattern) {
+    const segs = pattern.slice(1).split('/');
+    let score = isStaticPath(pattern) ? 1_000_000 : 0;
+    for (const s of segs)
+        score += s === '*' ? -1000 : s.startsWith(':') ? 1 : 100;
+    return score;
+}
+/** The address each page of a plugin is served at (owner's choice, else the plugin's default). */
+export function effectivePaths(install) {
+    const out = {};
+    for (const page of install.manifest.pages ?? [])
+        out[page.id] = install.paths[page.id] ?? page.path;
+    return out;
+}
+export function findPage(installs, pathname) {
+    const path = normalizePathname(pathname);
+    let best = null;
+    for (const install of Object.values(installs)) {
+        if (!install.enabled)
+            continue;
+        const paths = effectivePaths(install);
+        for (const page of install.manifest.pages ?? []) {
+            const pattern = paths[page.id];
+            const params = matchPattern(pattern, path);
+            if (!params)
+                continue;
+            const score = specificity(pattern);
+            if (!best || score > best.score)
+                best = { install, page, pattern, params, score };
+        }
+    }
+    return best;
+}
+/** Two patterns collide when they would match exactly the same addresses. */
+const shape = (pattern) => pattern
+    .split('/')
+    .map((s) => (s.startsWith(':') ? ':' : s))
+    .join('/');
+/**
+ * Check a page address before it is saved. Returns a sentence for the site
+ * owner when the address cannot be used, or null when it is fine.
+ */
+export function pathProblem(installs, pluginId, pageId, pattern, reserved) {
+    for (const prefix of reserved) {
+        if (pattern === prefix || pattern.startsWith(`${prefix}/`))
+            return `The address ${pattern} is reserved by the site.`;
+    }
+    for (const other of Object.values(installs)) {
+        const paths = effectivePaths(other);
+        for (const page of other.manifest.pages ?? []) {
+            if (other.id === pluginId && page.id === pageId)
+                continue;
+            if (shape(paths[page.id]) === shape(pattern))
+                return other.id === pluginId
+                    ? `The address ${pattern} is already used by another page of this plugin.`
+                    : `The address ${pattern} is already used by the plugin "${other.manifest.name}".`;
+        }
+    }
+    return null;
+}

package/dist/core/runtime.d.ts

@@ -0,0 +1,32 @@
+import type { AdminUser, PageResult, PluginContext, PluginServer, PluginStorage } from '@nextpluggable/plugin/server';
+import type { ResolvedConfig } from '../config.js';
+import type { InstallRecord } from './types.js';
+/** Identifies one exact build of a plugin's client bundle (used on both server and browser). */
+export declare function clientModuleKey(install: InstallRecord): string | null;
+export declare function assetUrl(cfg: ResolvedConfig, pluginId: string, sha256: string, file: 'client.js' | 'style.css'): string;
+/** Setting values safe to send to browsers, with defaults filled in. */
+export declare function publicConfig(install: InstallRecord): Record<string, unknown>;
+/** Every setting value, secrets decrypted. Server-side only. */
+export declare function serverConfig(cfg: ResolvedConfig, install: InstallRecord): Record<string, unknown>;
+export declare function pluginStorage(cfg: ResolvedConfig, pluginId: string): PluginStorage;
+export declare function pluginContext(cfg: ResolvedConfig, install: InstallRecord): PluginContext;
+/** Evaluate a plugin's server bundle (CommonJS, self-contained) and return what it exports. */
+export declare function evaluateServer(pluginId: string, code: string): PluginServer;
+/** The plugin's server module, or null when it has none. Cached by content hash. */
+export declare function loadServer(cfg: ResolvedConfig, install: InstallRecord): Promise<PluginServer | null>;
+export interface ClientAssets {
+    moduleKey: string;
+    scriptSrc: string;
+    styleHref?: string;
+}
+/**
+ * Make a plugin's client bundle available to the SSR pass of this process and
+ * return the URLs the browser loads it from.
+ */
+export declare function prepareClient(cfg: ResolvedConfig, install: InstallRecord): Promise<ClientAssets | null>;
+export declare function runPageLoader(cfg: ResolvedConfig, install: InstallRecord, pageId: string, input: {
+    path: string;
+    params: Record<string, string>;
+}): Promise<PageResult>;
+/** Dispatch a request to a plugin's API handlers (`"METHOD /path"` keys). */
+export declare function handlePluginApi(cfg: ResolvedConfig, install: InstallRecord, request: Request, subpath: string, admin: AdminUser | null): Promise<Response>;

package/dist/core/runtime.js

@@ -0,0 +1,190 @@
+import { defaultConfig, isPublicSetting } from '@nextpluggable/plugin/manifest';
+import { decrypt, isEncrypted } from '../crypto.js';
+import { jsonResponse, PluginGoneError } from '../errors.js';
+import { globals } from '../globals.js';
+import { decodeSegment } from '../storage/types.js';
+import { effectivePaths, matchPattern, normalizePathname } from './routes.js';
+import { dataKey, getFile } from './store.js';
+/** Identifies one exact build of a plugin's client bundle (used on both server and browser). */
+export function clientModuleKey(install) {
+    return install.files.client ? `${install.id}@${install.files.client.sha256.slice(0, 16)}` : null;
+}
+export function assetUrl(cfg, pluginId, sha256, file) {
+    return `${cfg.apiPath}/assets/${pluginId}/${sha256.slice(0, 16)}/${file}`;
+}
+/** Setting values safe to send to browsers, with defaults filled in. */
+export function publicConfig(install) {
+    const out = {};
+    const defaults = defaultConfig(install.manifest);
+    for (const field of install.manifest.settings ?? []) {
+        if (!isPublicSetting(field))
+            continue;
+        const v = install.config[field.key] ?? defaults[field.key];
+        if (v !== undefined)
+            out[field.key] = v;
+    }
+    return out;
+}
+/** Every setting value, secrets decrypted. Server-side only. */
+export function serverConfig(cfg, install) {
+    const out = { ...defaultConfig(install.manifest) };
+    for (const field of install.manifest.settings ?? []) {
+        const v = install.config[field.key];
+        if (v === undefined)
+            continue;
+        if (isEncrypted(v)) {
+            const plain = decrypt(cfg.secret, v);
+            if (plain !== null)
+                out[field.key] = plain;
+        }
+        else
+            out[field.key] = v;
+    }
+    return out;
+}
+export function pluginStorage(cfg, pluginId) {
+    const prefix = `data/${pluginId}/`;
+    return {
+        async get(key) {
+            const raw = await cfg.storage.get(dataKey(pluginId, key));
+            return raw === null ? null : JSON.parse(raw);
+        },
+        async set(key, value) {
+            const raw = JSON.stringify(value);
+            if (raw === undefined)
+                throw new Error('Only JSON values can be stored.');
+            if (raw.length > 1_000_000)
+                throw new Error('A stored value may be at most 1 MB.');
+            await cfg.storage.set(dataKey(pluginId, key), raw);
+        },
+        async delete(key) {
+            await cfg.storage.delete(dataKey(pluginId, key));
+        },
+        async list(keyPrefix = '') {
+            const keys = await cfg.storage.list(prefix);
+            return keys
+                .map((k) => decodeSegment(k.slice(prefix.length)))
+                .filter((k) => k.startsWith(keyPrefix))
+                .sort();
+        },
+    };
+}
+export function pluginContext(cfg, install) {
+    return {
+        pluginId: install.id,
+        config: serverConfig(cfg, install),
+        storage: pluginStorage(cfg, install.id),
+        site: { url: cfg.siteUrl },
+        paths: effectivePaths(install),
+        log: (...args) => console.log(`[plugin:${install.id}]`, ...args),
+    };
+}
+/** Evaluate a plugin's server bundle (CommonJS, self-contained) and return what it exports. */
+export function evaluateServer(pluginId, code) {
+    const getBuiltin = process.getBuiltinModule;
+    if (!getBuiltin)
+        throw new Error('Plugins with server code need Node.js 20.16 or newer.');
+    const mod = { exports: {} };
+    const req = (name) => {
+        const builtin = getBuiltin(name);
+        if (!builtin)
+            throw new Error(`Plugin "${pluginId}" tried to load "${name}", which is not available. Server bundles may only use Node built-ins at runtime.`);
+        return builtin;
+    };
+    // Plugins are trusted code chosen by the site owner; this is deliberate evaluation, not a sandbox.
+    new Function('require', 'module', 'exports', `${code}\n//# sourceURL=nextpluggable-plugin:///${pluginId}/server.js`)(req, mod, mod.exports);
+    const server = (mod.exports.default ?? mod.exports);
+    if (!server || typeof server !== 'object')
+        throw new Error(`Plugin "${pluginId}" has an invalid server entry.`);
+    return server;
+}
+/** The plugin's server module, or null when it has none. Cached by content hash. */
+export async function loadServer(cfg, install) {
+    const file = install.files.server;
+    if (!file)
+        return null;
+    const cache = globals().serverModules;
+    const key = `${install.id}@${file.sha256}`;
+    const hit = cache.get(key);
+    if (hit)
+        return hit;
+    const code = await getFile(cfg.storage, install.id, 'server', file.sha256);
+    if (code === null)
+        throw new PluginGoneError(install.id);
+    const server = evaluateServer(install.id, code);
+    for (const k of cache.keys())
+        if (k.startsWith(`${install.id}@`))
+            cache.delete(k);
+    cache.set(key, server);
+    return server;
+}
+/**
+ * Make a plugin's client bundle available to the SSR pass of this process and
+ * return the URLs the browser loads it from.
+ */
+export async function prepareClient(cfg, install) {
+    const client = install.files.client;
+    const moduleKey = clientModuleKey(install);
+    if (!client || !moduleKey)
+        return null;
+    const ssr = globals().ssrCode;
+    if (!ssr.has(moduleKey)) {
+        const code = await getFile(cfg.storage, install.id, 'client', client.sha256);
+        if (code === null)
+            throw new PluginGoneError(install.id);
+        for (const k of ssr.keys())
+            if (k.startsWith(`${install.id}@`))
+                ssr.delete(k);
+        ssr.set(moduleKey, code);
+    }
+    return {
+        moduleKey,
+        scriptSrc: assetUrl(cfg, install.id, client.sha256, 'client.js'),
+        styleHref: install.files.style ? assetUrl(cfg, install.id, install.files.style.sha256, 'style.css') : undefined,
+    };
+}
+export async function runPageLoader(cfg, install, pageId, input) {
+    const server = await loadServer(cfg, install);
+    const loader = server?.pages?.[pageId];
+    if (!loader)
+        return {};
+    const ctx = { ...pluginContext(cfg, install), ...input };
+    const result = await loader(ctx);
+    return result && typeof result === 'object' ? result : {};
+}
+/** Dispatch a request to a plugin's API handlers (`"METHOD /path"` keys). */
+export async function handlePluginApi(cfg, install, request, subpath, admin) {
+    let server;
+    try {
+        server = await loadServer(cfg, install);
+    }
+    catch (e) {
+        console.error(`[nextpluggable] Could not load plugin "${install.id}":`, e);
+        return jsonResponse({ error: 'This plugin could not be loaded.' }, 500);
+    }
+    const path = normalizePathname(subpath);
+    const method = request.method.toUpperCase() === 'HEAD' ? 'GET' : request.method.toUpperCase();
+    let methodMismatch = false;
+    for (const [key, handler] of Object.entries(server?.api ?? {})) {
+        const space = key.indexOf(' ');
+        const params = matchPattern(key.slice(space + 1), path);
+        if (!params)
+            continue;
+        if (key.slice(0, space) !== method) {
+            methodMismatch = true;
+            continue;
+        }
+        const ctx = { ...pluginContext(cfg, install), request, path, params, admin };
+        try {
+            const res = await handler(ctx);
+            if (!res || typeof res.status !== 'number' || typeof res.headers?.get !== 'function')
+                throw new Error(`Handler "${key}" did not return a Response.`);
+            return res;
+        }
+        catch (e) {
+            console.error(`[nextpluggable] Plugin "${install.id}" failed handling ${key}:`, e);
+            return jsonResponse({ error: 'The plugin ran into a problem handling this request.' }, 500);
+        }
+    }
+    return methodMismatch ? jsonResponse({ error: 'Method not allowed.' }, 405) : jsonResponse({ error: 'Not found.' }, 404);
+}