@nextpluggable/plugin 0.0.0-stage → 0.1.1

package/bin/nextpluggable-plugin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../dist/cli.js').catch((err) => {
+  console.error(err?.code === 'ERR_MODULE_NOT_FOUND' ? 'nextpluggable-plugin is not built yet. Run `pnpm --filter @nextpluggable/plugin build`.' : err);
+  process.exit(1);
+});

package/dist/build.d.ts

@@ -0,0 +1,21 @@
+import { type PluginBuild, type PluginManifest } from './manifest.js';
+/** Modules the host provides to client bundles at runtime. */
+export declare const SHARED_CLIENT_MODULES: readonly ["react", "react/jsx-runtime", "react-dom", "@nextpluggable/plugin"];
+export interface BuildPluginOptions {
+    minify?: boolean;
+    /** Called with human-readable progress lines. */
+    log?: (line: string) => void;
+    /** Called with advice that does not stop the build, such as a page with nothing to show in search results. */
+    warn?: (line: string) => void;
+}
+/**
+ * Things worth fixing for search engines that the manifest alone gives away. The
+ * site fills gaps with sensible values, so these are advice, not errors.
+ */
+export declare function seoAdvice(manifest: PluginManifest): string[];
+export declare class PluginBuildError extends Error {
+    constructor(message: string);
+}
+export declare function buildPlugin(dir: string, options?: BuildPluginOptions): Promise<PluginBuild>;
+/** Format any error from buildPlugin for a terminal. */
+export declare function describeBuildError(err: unknown): string;

package/dist/build.js

@@ -0,0 +1,251 @@
+/**
+ * Turns a plugin's source into the three artifacts a host installs:
+ *
+ *   dist/client.js   React components, as the body of a CommonJS module. `react`,
+ *                    `react-dom` and `@nextpluggable/plugin` stay external and are
+ *                    supplied by the host on both server (SSR) and browser.
+ *   dist/server.js   Page loaders + API handlers, self-contained CommonJS for Node.
+ *   dist/style.css   Any CSS imported by the client entry.
+ *   dist/build.json  Manifest + file hashes — the only file a host reads to list a plugin.
+ *
+ * `dist/` is meant to be committed, the same way JavaScript GitHub Actions ship,
+ * so that hosts can install straight from a repository at a pinned commit.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ManifestError, validateManifest } from './manifest.js';
+/** Modules the host provides to client bundles at runtime. */
+export const SHARED_CLIENT_MODULES = ['react', 'react/jsx-runtime', 'react-dom', '@nextpluggable/plugin'];
+const ASSET_LOADERS = {
+    '.svg': 'dataurl',
+    '.png': 'dataurl',
+    '.jpg': 'dataurl',
+    '.jpeg': 'dataurl',
+    '.gif': 'dataurl',
+    '.webp': 'dataurl',
+    '.woff2': 'dataurl',
+};
+/**
+ * Things worth fixing for search engines that the manifest alone gives away. The
+ * site fills gaps with sensible values, so these are advice, not errors.
+ */
+export function seoAdvice(manifest) {
+    const advice = [];
+    for (const page of manifest.pages ?? []) {
+        if (!page.description?.trim())
+            advice.push(`Page "${page.id}" has no "description". Search results will show the plugin's description instead; add one or two sentences written for visitors.`);
+        else if (page.description.length > 200)
+            advice.push(`Page "${page.id}" has a description of ${page.description.length} characters. Search engines cut it at about 160.`);
+        if (page.title.length > 65)
+            advice.push(`Page "${page.id}" has a title of ${page.title.length} characters. Search engines cut it at about 60.`);
+    }
+    return advice;
+}
+export class PluginBuildError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PluginBuildError';
+    }
+}
+function findEntry(dir, explicit, base) {
+    if (explicit) {
+        const p = path.resolve(dir, explicit);
+        if (!existsSync(p))
+            throw new PluginBuildError(`Entry file "${explicit}" does not exist.`);
+        return p;
+    }
+    for (const ext of ['tsx', 'ts', 'jsx', 'js', 'mjs']) {
+        const p = path.join(dir, 'src', `${base}.${ext}`);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+function exportsOf(meta) {
+    for (const [file, out] of Object.entries(meta.outputs))
+        if (file.endsWith('.js') && out.entryPoint)
+            return out.exports;
+    return [];
+}
+async function readManifest(dir) {
+    const file = path.join(dir, 'plugin.json');
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        throw new PluginBuildError(`No plugin.json found in ${dir}.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new PluginBuildError(`plugin.json is not valid JSON: ${e.message}`);
+    }
+    return validateManifest(parsed);
+}
+async function resolveIcon(dir, icon) {
+    if (!icon)
+        return undefined;
+    const m = /\.(svg|png|webp|jpe?g)$/i.exec(icon);
+    if (!m)
+        return icon; // an emoji / short text
+    const file = path.resolve(dir, icon);
+    if (!file.startsWith(path.resolve(dir) + path.sep))
+        throw new PluginBuildError('"icon" must be a file inside the plugin directory.');
+    const data = await readFile(file).catch(() => {
+        throw new PluginBuildError(`Icon file "${icon}" does not exist.`);
+    });
+    if (data.byteLength > 32_000)
+        throw new PluginBuildError(`Icon "${icon}" is larger than 32 KB.`);
+    const ext = m[1].toLowerCase();
+    const mime = ext === 'svg' ? 'image/svg+xml' : ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg';
+    return `data:${mime};base64,${data.toString('base64')}`;
+}
+/** Evaluate the built server bundle to check that what it exports lines up with the manifest. */
+function checkServer(code, manifest) {
+    const mod = { exports: {} };
+    const req = (name) => {
+        const builtin = process.getBuiltinModule(name);
+        if (!builtin)
+            throw new Error(`Cannot require "${name}": server bundles may only use Node built-ins at runtime.`);
+        return builtin;
+    };
+    try {
+        new Function('require', 'module', 'exports', code)(req, mod, mod.exports);
+    }
+    catch (e) {
+        throw new PluginBuildError(`The server entry throws when loaded: ${e.message}`);
+    }
+    const server = (mod.exports.default ?? mod.exports);
+    if (!server || typeof server !== 'object')
+        throw new PluginBuildError('The server entry must `export default definePluginServer({ ... })`.');
+    const pageIds = new Set((manifest.pages ?? []).map((p) => p.id));
+    if (server.pages !== undefined) {
+        if (typeof server.pages !== 'object' || server.pages === null)
+            throw new PluginBuildError('`pages` in the server entry must be an object.');
+        for (const [id, fn] of Object.entries(server.pages)) {
+            if (!pageIds.has(id))
+                throw new PluginBuildError(`The server entry has a loader for page "${id}", which plugin.json does not declare.`);
+            if (typeof fn !== 'function')
+                throw new PluginBuildError(`The loader for page "${id}" must be a function.`);
+        }
+    }
+    if (server.sitemap !== undefined && typeof server.sitemap !== 'function')
+        throw new PluginBuildError('`sitemap` in the server entry must be a function.');
+    if (server.api !== undefined) {
+        if (typeof server.api !== 'object' || server.api === null)
+            throw new PluginBuildError('`api` in the server entry must be an object.');
+        for (const [key, fn] of Object.entries(server.api)) {
+            if (!/^(GET|POST|PUT|PATCH|DELETE) \/\S*$/.test(key))
+                throw new PluginBuildError(`API route "${key}" must look like "GET /path" (methods: GET, POST, PUT, PATCH, DELETE).`);
+            if (typeof fn !== 'function')
+                throw new PluginBuildError(`API route "${key}" must be a function.`);
+        }
+    }
+}
+export async function buildPlugin(dir, options = {}) {
+    const log = options.log ?? (() => { });
+    const warn = options.warn ?? (() => { });
+    const { build } = await import('esbuild').catch(() => {
+        throw new PluginBuildError('Building plugins needs esbuild. Install it next to @nextpluggable/plugin: npm install --save-dev esbuild');
+    });
+    dir = path.resolve(dir);
+    const manifest = await readManifest(dir);
+    const clientEntry = findEntry(dir, manifest.entry?.client, 'client');
+    const serverEntry = findEntry(dir, manifest.entry?.server, 'server');
+    const components = [
+        ...(manifest.pages ?? []).map((p) => p.component),
+        ...(manifest.slots ?? []).map((s) => s.component),
+        ...(manifest.admin ?? []).map((a) => a.component),
+    ];
+    if (components.length && !clientEntry)
+        throw new PluginBuildError('plugin.json declares pages or components, but there is no client entry (expected src/client.tsx).');
+    if (!clientEntry && !serverEntry)
+        throw new PluginBuildError('Nothing to build: add src/client.tsx and/or src/server.ts.');
+    const outDir = path.join(dir, 'dist');
+    const outputs = [];
+    if (clientEntry) {
+        const shared = {
+            entryPoints: { client: clientEntry },
+            absWorkingDir: dir,
+            bundle: true,
+            platform: 'browser',
+            target: 'es2020',
+            jsx: 'automatic',
+            external: [...SHARED_CLIENT_MODULES],
+            define: { 'process.env.NODE_ENV': '"production"' },
+            loader: ASSET_LOADERS,
+            legalComments: 'none',
+            outdir: outDir,
+            write: false,
+            logLevel: 'silent',
+        };
+        // Pass 1 (ESM, discarded): learn the entry's export names.
+        const analysis = await build({ ...shared, format: 'esm', metafile: true });
+        const exported = new Set(exportsOf(analysis.metafile));
+        const missing = components.filter((c) => !exported.has(c));
+        if (missing.length)
+            throw new PluginBuildError(`plugin.json refers to component${missing.length > 1 ? 's' : ''} ${missing.map((c) => `"${c}"`).join(', ')}, but the client entry does not export ${missing.length > 1 ? 'them' : 'it'}.`);
+        // Pass 2: the real artifact.
+        const result = await build({ ...shared, format: 'cjs', minify: options.minify ?? true });
+        for (const f of result.outputFiles ?? []) {
+            if (f.path.endsWith('.js'))
+                outputs.push({ name: 'client', file: 'dist/client.js', contents: f.contents });
+            else if (f.path.endsWith('.css'))
+                outputs.push({ name: 'style', file: 'dist/style.css', contents: f.contents });
+        }
+    }
+    if (serverEntry) {
+        const shared = {
+            entryPoints: { server: serverEntry },
+            absWorkingDir: dir,
+            bundle: true,
+            platform: 'node',
+            target: 'node20',
+            outdir: outDir,
+            write: false,
+            legalComments: 'none',
+            logLevel: 'silent',
+        };
+        const analysis = await build({ ...shared, format: 'esm', metafile: true });
+        if (!exportsOf(analysis.metafile).includes('default'))
+            throw new PluginBuildError('The server entry must `export default definePluginServer({ ... })`.');
+        const result = await build({ ...shared, format: 'cjs', minifySyntax: true });
+        const js = result.outputFiles?.find((f) => f.path.endsWith('.js'));
+        if (!js)
+            throw new PluginBuildError('The server entry produced no output.');
+        checkServer(js.text, manifest);
+        outputs.push({ name: 'server', file: 'dist/server.js', contents: js.contents });
+    }
+    const files = {};
+    await rm(outDir, { recursive: true, force: true });
+    await mkdir(outDir, { recursive: true });
+    for (const o of outputs) {
+        await writeFile(path.join(dir, o.file), o.contents);
+        const entry = { path: o.file, sha256: sha256(o.contents), bytes: Buffer.byteLength(o.contents) };
+        files[o.name] = entry;
+        log(`  ${o.file}  ${(entry.bytes / 1024).toFixed(1)} kB`);
+    }
+    const pluginBuild = { buildVersion: 1, manifest, icon: await resolveIcon(dir, manifest.icon), files };
+    await writeFile(path.join(outDir, 'build.json'), JSON.stringify(pluginBuild, null, 2) + '\n');
+    log(`  dist/build.json`);
+    for (const line of seoAdvice(manifest))
+        warn(line);
+    return pluginBuild;
+}
+/** Format any error from buildPlugin for a terminal. */
+export function describeBuildError(err) {
+    if (err instanceof ManifestError || err instanceof PluginBuildError)
+        return err.message;
+    const e = err;
+    if (Array.isArray(e?.errors) && e.errors.length)
+        return e.errors
+            .map((x) => (x.location ? `${x.location.file}:${x.location.line}:${x.location.column}: ${x.text}` : x.text))
+            .join('\n');
+    return err instanceof Error ? (err.stack ?? err.message) : String(err);
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildPlugin, describeBuildError } from './build.js';
+import { validateManifest } from './manifest.js';
+const HELP = `nextpluggable-plugin — build tool for NextPluggable plugins
+
+Usage:
+  nextpluggable-plugin build [dir]      Build dist/ (client.js, server.js, style.css, build.json)
+  nextpluggable-plugin validate [dir]   Check plugin.json without building
+
+Options:
+  --no-minify    Keep the client bundle readable
+`;
+async function main() {
+    const args = process.argv.slice(2);
+    const flags = new Set(args.filter((a) => a.startsWith('--')));
+    const [command, dirArg] = args.filter((a) => !a.startsWith('--'));
+    const dir = path.resolve(dirArg ?? '.');
+    if (!command || flags.has('--help') || command === 'help') {
+        console.log(HELP);
+        return command ? 0 : 1;
+    }
+    if (command === 'validate') {
+        const manifest = validateManifest(JSON.parse(await readFile(path.join(dir, 'plugin.json'), 'utf8')));
+        console.log(`✓ ${manifest.name} ${manifest.version} — plugin.json is valid`);
+        return 0;
+    }
+    if (command === 'build') {
+        const started = Date.now();
+        const result = await buildPlugin(dir, { minify: !flags.has('--no-minify'), log: (l) => console.log(l), warn: (l) => console.log(`  ! ${l}`) });
+        console.log(`✓ Built ${result.manifest.name} ${result.manifest.version} in ${Date.now() - started} ms`);
+        return 0;
+    }
+    console.error(`Unknown command "${command}".\n\n${HELP}`);
+    return 1;
+}
+main().then((code) => process.exit(code), (err) => {
+    console.error(`✗ ${describeBuildError(err)}`);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import type { ComponentType, ReactNode } from 'react';
+export type { PluginManifest, SettingField, PluginPage } from './manifest.js';
+export interface PluginInfo {
+    id: string;
+    version: string;
+    /** Base URL of this plugin's HTTP API, e.g. `/api/nextpluggable/p/cart`. */
+    apiBase: string;
+    /** Present when rendered as a page. */
+    page?: {
+        id: string;
+        path: string;
+        params: Record<string, string>;
+    };
+    /** Addresses of this plugin's pages keyed by page id (as configured by the site owner). */
+    paths: Record<string, string>;
+}
+export interface LinkProps {
+    href: string;
+    children?: ReactNode;
+    className?: string;
+    style?: Record<string, string | number>;
+    title?: string;
+    'aria-label'?: string;
+}
+export interface Navigation {
+    pathname: string;
+    push(href: string): void;
+    replace(href: string): void;
+    back(): void;
+}
+/** Calls this plugin's own API. Path is relative to the plugin, e.g. `api('/items')`. */
+export type PluginApi = (path: string, init?: RequestInit & {
+    json?: unknown;
+}) => Promise<Response>;
+export interface HostRuntime {
+    usePluginConfig<T = Record<string, unknown>>(): T;
+    usePlugin(): PluginInfo;
+    usePluginApi(): PluginApi;
+    useNavigation(): Navigation;
+    useQuery(): URLSearchParams;
+    Link: ComponentType<LinkProps>;
+}
+/** The plugin's settings as filled in by the site owner (server-only and secret values excluded). */
+export declare function usePluginConfig<T = Record<string, unknown>>(): T;
+/** Identity and addresses of the running plugin. */
+export declare function usePlugin(): PluginInfo;
+/** A `fetch` bound to this plugin's API. Pass `{ json }` to send a JSON body. */
+export declare function usePluginApi(): PluginApi;
+/** Current location plus client-side navigation, provided by the host's router. */
+export declare function useNavigation(): Navigation;
+/**
+ * The page's query string, for filters, searches and the like. It is only ever
+ * known in the browser: it is empty during server rendering and on the first
+ * render there, then fills in. (Pages may be cached and shared between
+ * visitors, so the server never puts a query string into HTML.)
+ */
+export declare function useQuery(): URLSearchParams;
+/** Client-side link rendered with the host's router. */
+export declare const Link: ComponentType<LinkProps>;
+/** Props every page component receives in addition to what its server loader returned. */
+export interface PageProps<P = Record<string, unknown>> {
+    params: Record<string, string>;
+    data: P;
+}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * Client-side API for plugin authors.
+ *
+ * `nextpluggable-plugin build` never bundles this module: it is left as an
+ * external and the host site supplies the real implementation at load time, so
+ * a plugin shares the host's React, router and context instead of shipping its own.
+ */
+import { createElement } from 'react';
+const HOST_KEY = Symbol.for('nextpluggable.host-runtime');
+function host() {
+    const h = globalThis[HOST_KEY];
+    if (!h)
+        throw new Error('@nextpluggable/plugin was used outside a NextPluggable host. Build the plugin with `nextpluggable-plugin build` and install it from the dashboard.');
+    return h;
+}
+/** The plugin's settings as filled in by the site owner (server-only and secret values excluded). */
+export function usePluginConfig() {
+    return host().usePluginConfig();
+}
+/** Identity and addresses of the running plugin. */
+export function usePlugin() {
+    return host().usePlugin();
+}
+/** A `fetch` bound to this plugin's API. Pass `{ json }` to send a JSON body. */
+export function usePluginApi() {
+    return host().usePluginApi();
+}
+/** Current location plus client-side navigation, provided by the host's router. */
+export function useNavigation() {
+    return host().useNavigation();
+}
+/**
+ * The page's query string, for filters, searches and the like. It is only ever
+ * known in the browser: it is empty during server rendering and on the first
+ * render there, then fills in. (Pages may be cached and shared between
+ * visitors, so the server never puts a query string into HTML.)
+ */
+export function useQuery() {
+    return host().useQuery();
+}
+/** Client-side link rendered with the host's router. */
+export const Link = (props) => createElement(host().Link, props);

package/dist/manifest.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The plugin manifest (`plugin.json`) — the contract between a plugin and any host.
+ * Everything a non-technical site owner sees about a plugin (name, what it adds,
+ * its settings form, what it is allowed to do) is derived from this file.
+ */
+export declare const MANIFEST_VERSION = 1;
+export type SettingType = 'text' | 'textarea' | 'number' | 'toggle' | 'select' | 'color' | 'url' | 'email' | 'secret';
+export interface SettingOption {
+    value: string;
+    label: string;
+}
+export interface SettingField {
+    /** Key under which the value is exposed in the plugin's config object. */
+    key: string;
+    /** Human label shown in the settings form. */
+    label: string;
+    type: SettingType;
+    /** One plain-language sentence shown under the field. */
+    help?: string;
+    default?: string | number | boolean;
+    required?: boolean;
+    placeholder?: string;
+    /** Section heading the field is grouped under in the form. */
+    group?: string;
+    /** `select` only. */
+    options?: SettingOption[];
+    /** `number` only. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /**
+     * Keep the value on the server (never sent to browsers). `secret` fields are
+     * always server-only and are additionally encrypted at rest.
+     */
+    serverOnly?: boolean;
+}
+export interface PluginPage {
+    /** Stable id; the server entry's `pages[id]` loader is matched by it. */
+    id: string;
+    /**
+     * Default address of the page, e.g. `/emi-calculator` or `/shop/:slug`.
+     * `:name` matches one segment, a trailing `*` matches the rest.
+     */
+    path: string;
+    /** Name of the React component exported from the client entry. */
+    component: string;
+    /** Shown in the dashboard ("Adds a page: EMI Calculator"). Also the default <title>. */
+    title: string;
+    description?: string;
+    /** Let the site owner change the address from the dashboard. Default true for static paths. */
+    configurablePath?: boolean;
+}
+export interface PluginSlotContribution {
+    /** Name of a `<Slot name="…">` the host site renders, e.g. `header.actions`, `body.end`. */
+    slot: string;
+    component: string;
+    order?: number;
+}
+export interface PluginAdminPage {
+    id: string;
+    /** Tab title in the dashboard, e.g. "Messages". */
+    title: string;
+    component: string;
+}
+/**
+ * What the plugin does on the server, in plain language. Shown to the site
+ * owner before installing. (v1 hosts display these; sandboxed hosts enforce them.)
+ */
+export type PluginPermission = 'storage' | 'email' | `fetch:${string}`;
+export interface PluginManifest {
+    manifestVersion: typeof MANIFEST_VERSION;
+    /** Globally unique, URL-safe id: lowercase letters, digits, dashes. */
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    homepage?: string;
+    /** An emoji, or a path to a small .svg/.png relative to the plugin directory. */
+    icon?: string;
+    category?: string;
+    /** Source entry points (used by the build only). */
+    entry?: {
+        client?: string;
+        server?: string;
+    };
+    pages?: PluginPage[];
+    slots?: PluginSlotContribution[];
+    admin?: PluginAdminPage[];
+    settings?: SettingField[];
+    permissions?: PluginPermission[];
+}
+/** Written by `nextpluggable-plugin build` to `dist/build.json`; the only file a host must read to list a plugin. */
+export interface PluginBuild {
+    buildVersion: 1;
+    manifest: PluginManifest;
+    /** Icon resolved to something directly renderable (emoji or data: URI). */
+    icon?: string;
+    files: {
+        client?: BuiltFile;
+        server?: BuiltFile;
+        style?: BuiltFile;
+    };
+}
+export interface BuiltFile {
+    /** Path relative to the plugin directory. */
+    path: string;
+    sha256: string;
+    bytes: number;
+}
+/** Optional `nextpluggable.json` at the root of a repository that hosts several plugins. */
+export interface RepositoryIndex {
+    name?: string;
+    description?: string;
+    /** Plugin directories relative to the repository root. */
+    plugins: string[];
+}
+export declare class ManifestError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/** Validate a page path pattern. Returns a problem description, or null when fine. */
+export declare function checkPagePath(path: unknown): string | null;
+export declare function isStaticPath(path: string): boolean;
+/**
+ * Validate an untrusted value as a manifest. Throws ManifestError listing every
+ * problem in words a plugin author can act on.
+ */
+export declare function validateManifest(input: unknown): PluginManifest;
+/** Default values declared by the manifest's settings. */
+export declare function defaultConfig(manifest: PluginManifest): Record<string, string | number | boolean>;
+/** Whether a setting's value may be sent to browsers. */
+export declare function isPublicSetting(field: SettingField): boolean;
+/**
+ * Check and normalise values submitted for a plugin's settings.
+ * Returns cleaned values plus per-field messages written for a non-technical reader.
+ */
+export declare function validateSettings(manifest: PluginManifest, input: Record<string, unknown>): {
+    values: Record<string, string | number | boolean>;
+    errors: Record<string, string>;
+};
+export declare function validateRepositoryIndex(input: unknown): RepositoryIndex;
+export declare function validateBuild(input: unknown): PluginBuild;