nextpluggable 0.0.0-stage → 0.1.0

package/dist/client/island.js

@@ -0,0 +1,177 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Renders a component from a plugin bundle that was not part of this site's build.
+ *
+ * Server (SSR pass): the bundle's source was placed in process memory by the
+ * server component that rendered us; it is evaluated here with THIS module
+ * graph's React, so the plugin renders into the same tree as the rest of the page.
+ *
+ * Browser: the same bundle arrives as a <script>, registers itself, and is
+ * given the browser's React. `use()` suspends until it has, and React keeps the
+ * server-rendered HTML in place and hydrates it once the module is ready.
+ */
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import * as jsxRuntime from 'react/jsx-runtime';
+import { hostRuntime, PluginRuntimeContext } from './host-runtime.js';
+import { ClientOnly, createGuardedRuntime } from './ssr-guard.js';
+const shared = {
+    react: React,
+    'react/jsx-runtime': jsxRuntime,
+    'react-dom': ReactDOM,
+    '@nextpluggable/plugin': hostRuntime,
+};
+function hostRequire(name) {
+    if (name in shared)
+        return shared[name];
+    throw new Error(`A plugin tried to load "${name}", which this site does not provide. Bundle it into the plugin instead.`);
+}
+function instantiate(factory, require = hostRequire) {
+    const module = { exports: {} };
+    factory(require, module, module.exports);
+    return module.exports;
+}
+/** Server only: the crash guard each plugin bundle was instantiated with. */
+const guards = new Map();
+function settled(value) {
+    const p = Promise.resolve(value);
+    p.status = 'fulfilled';
+    p.value = value;
+    return p;
+}
+function failed(reason) {
+    const p = Promise.reject(reason);
+    p.catch(() => { });
+    p.status = 'rejected';
+    p.reason = reason;
+    return p;
+}
+const modules = new Map();
+const pending = new Map();
+const LOAD_TIMEOUT_MS = 20_000;
+function register(key, factory) {
+    const waiter = pending.get(key);
+    pending.delete(key);
+    try {
+        const mod = instantiate(factory);
+        if (waiter)
+            waiter.resolve(mod);
+        else
+            modules.set(key, settled(mod));
+    }
+    catch (e) {
+        if (waiter)
+            waiter.reject(e);
+        else
+            modules.set(key, failed(e));
+    }
+}
+if (typeof window !== 'undefined') {
+    // Bundles that arrived before this module ran queued themselves; later ones call straight in.
+    const w = window;
+    const queued = Array.isArray(w.__NP_Q__) ? w.__NP_Q__ : [];
+    w.__NP_Q__ = { push: (entry) => register(entry[0], entry[1]) };
+    for (const entry of queued)
+        register(entry[0], entry[1]);
+}
+function loadModule(key, src) {
+    const existing = modules.get(key);
+    if (existing)
+        return existing;
+    let tracked;
+    if (typeof window === 'undefined') {
+        const state = globalThis[Symbol.for('nextpluggable.state')];
+        const code = state?.ssrCode?.get(key);
+        // Keep only the newest build of each plugin in memory.
+        const prefix = `${key.split('@')[0]}@`;
+        for (const k of modules.keys())
+            if (k.startsWith(prefix))
+                (modules.delete(k), guards.delete(k));
+        try {
+            if (code === undefined)
+                throw new Error(`Plugin bundle ${key} was not prepared for server rendering.`);
+            // On the server the plugin is given a React that contains its crashes (see ssr-guard).
+            const guarded = createGuardedRuntime(`Plugin "${key.split('@')[0]}"`);
+            guards.set(key, guarded);
+            const guardedRequire = (name) => (name === 'react' ? guarded.react : name === 'react/jsx-runtime' ? guarded.jsxRuntime : hostRequire(name));
+            tracked = settled(instantiate(new Function('require', 'module', 'exports', `${code}\n//# sourceURL=nextpluggable-plugin:///${key}/client.js`), guardedRequire));
+        }
+        catch (e) {
+            console.error(`[nextpluggable] Plugin bundle ${key} could not be loaded on the server and was left out of the page:`, e);
+            tracked = failed(e);
+        }
+    }
+    else {
+        tracked = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(key);
+                reject(new Error(`Timed out loading plugin bundle ${key}.`));
+            }, LOAD_TIMEOUT_MS);
+            pending.set(key, {
+                resolve: (m) => {
+                    clearTimeout(timer);
+                    resolve(m);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            if (!document.querySelector(`script[src="${CSS.escape(src)}"]`)) {
+                const script = document.createElement('script');
+                script.src = src;
+                script.async = true;
+                script.onerror = () => {
+                    clearTimeout(timer);
+                    pending.delete(key);
+                    reject(new Error(`Could not load plugin bundle ${key}.`));
+                };
+                document.head.appendChild(script);
+            }
+        });
+        tracked.then((value) => {
+            tracked.status = 'fulfilled';
+            tracked.value = value;
+        }, (reason) => {
+            tracked.status = 'rejected';
+            tracked.reason = reason;
+        });
+    }
+    modules.set(key, tracked);
+    return tracked;
+}
+function Loaded(props) {
+    const tracked = loadModule(props.moduleKey, props.src);
+    if (typeof window === 'undefined') {
+        // A bundle that failed to load must not fail the page: leave it to the browser, where the error boundary handles it.
+        const Component = tracked.status === 'fulfilled' ? tracked.value?.[props.component] : undefined;
+        if (typeof Component !== 'function')
+            return _jsx(ClientOnly, {});
+        const Guarded = (guards.get(props.moduleKey)?.guard(Component) ?? Component);
+        return _jsx(Guarded, { ...props.componentProps });
+    }
+    const mod = React.use(tracked);
+    const Component = mod[props.component];
+    if (typeof Component !== 'function')
+        throw new Error(`Plugin bundle ${props.moduleKey} does not export "${props.component}".`);
+    return _jsx(Component, { ...props.componentProps });
+}
+class Boundary extends React.Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        console.error(`[nextpluggable] ${this.props.label} failed to render:`, error);
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+export function PluginIsland(p) {
+    // Start fetching the bundle as early as possible; during SSR this emits an async <script> in the document head.
+    ReactDOM.preinit(p.src, { as: 'script' });
+    const value = React.useMemo(() => ({ info: p.info, config: p.config }), [p.info, p.config]);
+    return (_jsx(PluginRuntimeContext.Provider, { value: value, children: _jsx(Boundary, { fallback: p.errorFallback ?? null, label: `Plugin "${p.info.id}"`, children: _jsx(React.Suspense, { fallback: p.loadingFallback ?? null, children: _jsx(Loaded, { moduleKey: p.moduleKey, src: p.src, component: p.component, componentProps: p.props ?? {} }) }) }) }));
+}

package/dist/client/ssr-guard.d.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import * as jsxRuntime from 'react/jsx-runtime';
+/** Renders nothing in the browser; on the server it hands the enclosing Suspense boundary over to client rendering. */
+export declare const ClientOnly: React.ComponentType<{}>;
+export interface GuardedRuntime {
+    /** Wrap one component type. */
+    guard<T>(type: T): T;
+    react: typeof React;
+    jsxRuntime: typeof jsxRuntime;
+}
+export declare function createGuardedRuntime(label: string): GuardedRuntime;

package/dist/client/ssr-guard.js

@@ -0,0 +1,100 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Keeps a crashing plugin from failing the server render of the page around it.
+ *
+ * React has no error boundaries on the server: a component that throws there
+ * fails the nearest Suspense boundary, and for statically cached pages Next.js
+ * then (rightly) refuses to produce the page at all. A widget in the site's
+ * layout would take every page down with it.
+ *
+ * Plugins get React from the host, so on the server the host hands them a
+ * React whose element factories wrap every plugin function component in a
+ * try/catch. When one throws, it is replaced by a client-only placeholder:
+ * the page is produced without that plugin's HTML and the browser renders the
+ * plugin itself. If it throws there too, the island's error boundary shows the
+ * fallback; if it only failed on the server (say, it read `window` while
+ * rendering), it simply works.
+ */
+import dynamic from 'next/dynamic';
+import * as React from 'react';
+import * as jsxRuntime from 'react/jsx-runtime';
+/** Renders nothing in the browser; on the server it hands the enclosing Suspense boundary over to client rendering. */
+export const ClientOnly = dynamic(() => Promise.resolve({ default: () => null }), { ssr: false });
+const MEMO = Symbol.for('react.memo');
+const FORWARD_REF = Symbol.for('react.forward_ref');
+/** Things components throw on purpose: suspending (a promise, or React's own marker) and framework control flow. */
+function isControlFlow(e) {
+    if (e === null || typeof e !== 'object')
+        return false;
+    const x = e;
+    return typeof x.then === 'function' || typeof x.digest === 'string' || (typeof x.message === 'string' && x.message.startsWith('Suspense Exception'));
+}
+export function createGuardedRuntime(label) {
+    const wrapped = new WeakMap();
+    let reported = false;
+    const crashed = (error) => {
+        if (!reported) {
+            reported = true;
+            console.error(`[nextpluggable] ${label} crashed while rendering on the server and was left out of the page:`, error);
+        }
+        return _jsx(ClientOnly, {});
+    };
+    function guard(type) {
+        if (type === null || (typeof type !== 'function' && typeof type !== 'object'))
+            return type;
+        const hit = wrapped.get(type);
+        if (hit)
+            return hit;
+        let result = type;
+        const t = type;
+        if (typeof type === 'function') {
+            // Class components cannot be called directly; they stay as they are.
+            if (!t.prototype?.isReactComponent) {
+                const component = type;
+                const Guarded = (props) => {
+                    try {
+                        return component(props);
+                    }
+                    catch (e) {
+                        if (isControlFlow(e))
+                            throw e;
+                        return crashed(e);
+                    }
+                };
+                Guarded.displayName = t.displayName ?? t.name;
+                result = Guarded;
+            }
+        }
+        else if (t.$$typeof === MEMO) {
+            const inner = guard(t.type);
+            if (inner !== t.type)
+                result = React.memo(inner, t.compare);
+        }
+        else if (t.$$typeof === FORWARD_REF) {
+            const render = t.render;
+            result = React.forwardRef((props, ref) => {
+                try {
+                    return render(props, ref);
+                }
+                catch (e) {
+                    if (isControlFlow(e))
+                        throw e;
+                    return crashed(e);
+                }
+            });
+        }
+        wrapped.set(type, result);
+        return result;
+    }
+    const jsx = jsxRuntime;
+    return {
+        guard,
+        react: { ...React, createElement: (type, ...rest) => React.createElement(guard(type), ...rest) },
+        jsxRuntime: {
+            ...jsxRuntime,
+            jsx: (type, ...rest) => jsx.jsx(guard(type), ...rest),
+            jsxs: (type, ...rest) => jsx.jsxs(guard(type), ...rest),
+        },
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,46 @@
+import type { AuthAdapter } from './auth/types.js';
+import type { StorageAdapter } from './storage/types.js';
+export interface NextPluggableConfig {
+    /** Who may use the dashboard. Default: `passwordAuth()` reading `NEXTPLUGGABLE_PASSWORD`. */
+    auth?: AuthAdapter;
+    /** Where data lives. Default: `fileStorage()` (a `.nextpluggable` folder). */
+    storage?: StorageAdapter;
+    /** Signs sessions and encrypts stored secrets. Default: `NEXTPLUGGABLE_SECRET`. Required in production. */
+    secret?: string;
+    /** URL path of the dashboard. Must match where you put the dashboard page. Default `/admin/plugins`. */
+    dashboardPath?: string;
+    /** URL path of the API route. Must match where you put the route handler. Default `/api/nextpluggable`. */
+    apiPath?: string;
+    /** Public origin of the site, e.g. `https://example.com`. Default: `NEXT_PUBLIC_SITE_URL`, then the host's own URL. */
+    siteUrl?: string;
+    /** Shown in the dashboard header. */
+    siteName?: string;
+    github?: {
+        /** API base, for GitHub Enterprise. Default `https://api.github.com`. */
+        apiUrl?: string;
+        /** A token used for every GitHub source that has none of its own. Default: `NEXTPLUGGABLE_GITHUB_TOKEN`. */
+        token?: string;
+    };
+    /** Allow plugin sources that are folders on the server. Default: only outside production, or when `NEXTPLUGGABLE_ALLOW_LOCAL_SOURCES=1`. */
+    allowLocalSources?: boolean;
+    /** How long the list of installed plugins is cached in memory per server instance. Default 5000 (0 in development). */
+    cacheTtlMs?: number;
+}
+export interface ResolvedConfig {
+    auth: AuthAdapter;
+    storage: StorageAdapter;
+    secret: string;
+    dashboardPath: string;
+    apiPath: string;
+    siteUrl: string;
+    siteName: string;
+    githubApiUrl: string;
+    githubToken: string | undefined;
+    allowLocalSources: boolean;
+    cacheTtlMs: number;
+}
+/**
+ * Settings are resolved lazily (on first use, not at import) so that `next build`
+ * succeeds in environments where runtime secrets are not present.
+ */
+export declare function resolveConfig(config: NextPluggableConfig): () => ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,55 @@
+import { passwordAuth } from './auth/password.js';
+import { warnOnce } from './globals.js';
+import { fileStorage } from './storage/file.js';
+function cleanPath(value, name) {
+    const p = `/${value}`.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+    if (!/^(\/[A-Za-z0-9._~-]+)+$/.test(p))
+        throw new Error(`[nextpluggable] "${name}" must be a URL path like "/admin/plugins" (got ${JSON.stringify(value)}).`);
+    return p;
+}
+function defaultSiteUrl() {
+    const explicit = process.env.NEXT_PUBLIC_SITE_URL ?? process.env.SITE_URL;
+    if (explicit)
+        return explicit;
+    if (process.env.VERCEL_PROJECT_PRODUCTION_URL)
+        return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`;
+    if (process.env.VERCEL_URL)
+        return `https://${process.env.VERCEL_URL}`;
+    return `http://localhost:${process.env.PORT ?? 3000}`;
+}
+/**
+ * Settings are resolved lazily (on first use, not at import) so that `next build`
+ * succeeds in environments where runtime secrets are not present.
+ */
+export function resolveConfig(config) {
+    let resolved;
+    return () => {
+        if (resolved)
+            return resolved;
+        const production = process.env.NODE_ENV === 'production';
+        let secret = config.secret ?? process.env.NEXTPLUGGABLE_SECRET;
+        if (!secret) {
+            if (production)
+                throw new Error('[nextpluggable] NEXTPLUGGABLE_SECRET is not set. Add a long random value to your environment (for example the output of `openssl rand -base64 32`).');
+            warnOnce('dev-secret', 'NEXTPLUGGABLE_SECRET is not set; using an insecure development secret.');
+            secret = 'nextpluggable-insecure-development-secret';
+        }
+        else if (secret.length < 16) {
+            throw new Error('[nextpluggable] NEXTPLUGGABLE_SECRET is too short. Use at least 16 characters.');
+        }
+        resolved = {
+            auth: config.auth ?? passwordAuth(),
+            storage: config.storage ?? fileStorage(),
+            secret,
+            dashboardPath: cleanPath(config.dashboardPath ?? '/admin/plugins', 'dashboardPath'),
+            apiPath: cleanPath(config.apiPath ?? '/api/nextpluggable', 'apiPath'),
+            siteUrl: (config.siteUrl ?? defaultSiteUrl()).replace(/\/+$/, ''),
+            siteName: config.siteName ?? 'Your site',
+            githubApiUrl: (config.github?.apiUrl ?? process.env.NEXTPLUGGABLE_GITHUB_API_URL ?? 'https://api.github.com').replace(/\/+$/, ''),
+            githubToken: config.github?.token ?? process.env.NEXTPLUGGABLE_GITHUB_TOKEN ?? undefined,
+            allowLocalSources: config.allowLocalSources ?? (!production || process.env.NEXTPLUGGABLE_ALLOW_LOCAL_SOURCES === '1'),
+            cacheTtlMs: config.cacheTtlMs ?? (production ? 5000 : 0),
+        };
+        return resolved;
+    };
+}

package/dist/core/installer.d.ts

@@ -0,0 +1,30 @@
+import type { PluginManifest } from '@nextpluggable/plugin/manifest';
+import type { ResolvedConfig } from '../config.js';
+import type { Catalog, InstallRecord, SourceRecord } from './types.js';
+/** True while a required setting has no value — the plugin stays paused until the owner fills it in. */
+export declare function needsSetup(manifest: PluginManifest, config: InstallRecord['config']): boolean;
+export declare function addSource(cfg: ResolvedConfig, input: {
+    url?: unknown;
+    token?: unknown;
+}): Promise<SourceRecord>;
+export declare function refreshSource(cfg: ResolvedConfig, source: SourceRecord): Promise<Catalog>;
+/** Refresh every source; one failing source does not stop the others. */
+export declare function refreshAllSources(cfg: ResolvedConfig): Promise<{
+    label: string;
+    message: string;
+}[]>;
+export declare function removeSource(cfg: ResolvedConfig, sourceId: string): Promise<void>;
+export declare function installPlugin(cfg: ResolvedConfig, input: {
+    sourceId?: unknown;
+    path?: unknown;
+}): Promise<InstallRecord>;
+export declare function updatePlugin(cfg: ResolvedConfig, pluginId: string): Promise<InstallRecord>;
+export interface PluginPatch {
+    enabled?: unknown;
+    config?: unknown;
+    paths?: unknown;
+}
+export declare function changePlugin(cfg: ResolvedConfig, pluginId: string, patch: PluginPatch): Promise<InstallRecord>;
+export declare function uninstallPlugin(cfg: ResolvedConfig, pluginId: string, options?: {
+    deleteData?: boolean;
+}): Promise<void>;