@nextpluggable/plugin 0.0.0-stage → 0.1.0

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,14 @@
+import { type PluginBuild } 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;
+}
+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,230 @@
+/**
+ * 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',
+};
+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.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 { 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`);
+    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) });
+        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;

package/dist/manifest.js

@@ -0,0 +1,348 @@
+/**
+ * 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 const MANIFEST_VERSION = 1;
+const ID_RE = /^[a-z][a-z0-9-]{1,48}[a-z0-9]$/;
+const KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+const COMPONENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SLOT_RE = /^[a-z][a-z0-9.-]{0,63}$/;
+/** Names that collide with built-in object properties; refusing them keeps every lookup by id/key safe. */
+const RESERVED = new Set(['constructor', 'prototype', 'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable', 'toLocaleString', 'toString', 'valueOf']);
+const isKey = (v) => typeof v === 'string' && KEY_RE.test(v) && !RESERVED.has(v);
+const SETTING_TYPES = [
+    'text',
+    'textarea',
+    'number',
+    'toggle',
+    'select',
+    'color',
+    'url',
+    'email',
+    'secret',
+];
+export class ManifestError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Invalid plugin manifest:\n- ${problems.join('\n- ')}`);
+        this.problems = problems;
+        this.name = 'ManifestError';
+    }
+}
+/** Validate a page path pattern. Returns a problem description, or null when fine. */
+export function checkPagePath(path) {
+    if (typeof path !== 'string' || !path.startsWith('/'))
+        return 'must start with "/"';
+    if (path.length > 200)
+        return 'is too long';
+    if (path !== '/' && path.endsWith('/'))
+        return 'must not end with "/"';
+    if (path === '/')
+        return 'cannot be the home page';
+    const segments = path.slice(1).split('/');
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (seg === '*') {
+            if (i !== segments.length - 1)
+                return '"*" is only allowed as the last segment';
+            continue;
+        }
+        if (seg.startsWith(':')) {
+            if (!KEY_RE.test(seg.slice(1)))
+                return `has an invalid parameter name "${seg}"`;
+            continue;
+        }
+        if (!/^[A-Za-z0-9._~-]+$/.test(seg) || seg === '.' || seg === '..')
+            return `has an invalid segment "${seg}" (use letters, digits, dashes)`;
+    }
+    return null;
+}
+export function isStaticPath(path) {
+    return !path.split('/').some((s) => s === '*' || s.startsWith(':'));
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Validate an untrusted value as a manifest. Throws ManifestError listing every
+ * problem in words a plugin author can act on.
+ */
+export function validateManifest(input) {
+    const p = [];
+    if (!isRecord(input))
+        throw new ManifestError(['manifest must be a JSON object']);
+    const m = input;
+    if (m.manifestVersion !== MANIFEST_VERSION)
+        p.push(`"manifestVersion" must be ${MANIFEST_VERSION}`);
+    if (typeof m.id !== 'string' || !ID_RE.test(m.id) || RESERVED.has(m.id))
+        p.push('"id" must be 3-50 characters: lowercase letters, digits and dashes, starting with a letter');
+    if (typeof m.name !== 'string' || !m.name.trim() || m.name.length > 80)
+        p.push('"name" is required (max 80 characters)');
+    if (typeof m.version !== 'string' || !VERSION_RE.test(m.version))
+        p.push('"version" must look like 1.2.3');
+    for (const k of ['description', 'author', 'homepage', 'icon', 'category']) {
+        if (m[k] !== undefined && typeof m[k] !== 'string')
+            p.push(`"${k}" must be text`);
+    }
+    if (typeof m.description === 'string' && m.description.length > 500)
+        p.push('"description" is too long (max 500 characters)');
+    if (m.entry !== undefined) {
+        if (!isRecord(m.entry))
+            p.push('"entry" must be an object');
+        else
+            for (const k of ['client', 'server'])
+                if (m.entry[k] !== undefined && typeof m.entry[k] !== 'string')
+                    p.push(`"entry.${k}" must be a file path`);
+    }
+    const pageIds = new Set();
+    const pagePaths = new Set();
+    if (m.pages !== undefined) {
+        if (!Array.isArray(m.pages))
+            p.push('"pages" must be a list');
+        else
+            m.pages.forEach((page, i) => {
+                const at = `pages[${i}]`;
+                if (!isRecord(page))
+                    return void p.push(`${at} must be an object`);
+                if (!isKey(page.id))
+                    p.push(`${at}.id must be a short identifier`);
+                else if (pageIds.has(page.id))
+                    p.push(`${at}.id "${page.id}" is used twice`);
+                else
+                    pageIds.add(page.id);
+                const pathProblem = checkPagePath(page.path);
+                if (pathProblem)
+                    p.push(`${at}.path ${pathProblem}`);
+                else if (pagePaths.has(page.path))
+                    p.push(`${at}.path "${String(page.path)}" is used twice`);
+                else
+                    pagePaths.add(page.path);
+                if (typeof page.component !== 'string' || !COMPONENT_RE.test(page.component))
+                    p.push(`${at}.component must be the name of an exported component`);
+                if (typeof page.title !== 'string' || !page.title.trim())
+                    p.push(`${at}.title is required`);
+                if (page.description !== undefined && typeof page.description !== 'string')
+                    p.push(`${at}.description must be text`);
+                if (page.configurablePath !== undefined && typeof page.configurablePath !== 'boolean')
+                    p.push(`${at}.configurablePath must be true or false`);
+            });
+    }
+    if (m.slots !== undefined) {
+        if (!Array.isArray(m.slots))
+            p.push('"slots" must be a list');
+        else
+            m.slots.forEach((slot, i) => {
+                const at = `slots[${i}]`;
+                if (!isRecord(slot))
+                    return void p.push(`${at} must be an object`);
+                if (typeof slot.slot !== 'string' || !SLOT_RE.test(slot.slot))
+                    p.push(`${at}.slot must be a slot name like "header.actions"`);
+                if (typeof slot.component !== 'string' || !COMPONENT_RE.test(slot.component))
+                    p.push(`${at}.component must be the name of an exported component`);
+                if (slot.order !== undefined && typeof slot.order !== 'number')
+                    p.push(`${at}.order must be a number`);
+            });
+    }
+    if (m.admin !== undefined) {
+        const ids = new Set();
+        if (!Array.isArray(m.admin))
+            p.push('"admin" must be a list');
+        else
+            m.admin.forEach((a, i) => {
+                const at = `admin[${i}]`;
+                if (!isRecord(a))
+                    return void p.push(`${at} must be an object`);
+                if (!isKey(a.id))
+                    p.push(`${at}.id must be a short identifier`);
+                else if (ids.has(a.id))
+                    p.push(`${at}.id "${a.id}" is used twice`);
+                else
+                    ids.add(a.id);
+                if (typeof a.title !== 'string' || !a.title.trim())
+                    p.push(`${at}.title is required`);
+                if (typeof a.component !== 'string' || !COMPONENT_RE.test(a.component))
+                    p.push(`${at}.component must be the name of an exported component`);
+            });
+    }
+    if (m.settings !== undefined) {
+        const keys = new Set();
+        if (!Array.isArray(m.settings))
+            p.push('"settings" must be a list');
+        else
+            m.settings.forEach((f, i) => {
+                const at = `settings[${i}]`;
+                if (!isRecord(f))
+                    return void p.push(`${at} must be an object`);
+                if (!isKey(f.key))
+                    p.push(`${at}.key must be a short identifier`);
+                else if (keys.has(f.key))
+                    p.push(`${at}.key "${f.key}" is used twice`);
+                else
+                    keys.add(f.key);
+                if (typeof f.label !== 'string' || !f.label.trim())
+                    p.push(`${at}.label is required`);
+                if (!SETTING_TYPES.includes(f.type))
+                    p.push(`${at}.type must be one of: ${SETTING_TYPES.join(', ')}`);
+                if (f.type === 'select') {
+                    if (!Array.isArray(f.options) || f.options.length === 0)
+                        p.push(`${at}.options is required for a select`);
+                    else if (!f.options.every((o) => isRecord(o) && typeof o.value === 'string' && typeof o.label === 'string'))
+                        p.push(`${at}.options must be a list of { value, label }`);
+                }
+                if (f.type === 'secret' && f.default !== undefined)
+                    p.push(`${at} is a secret and cannot have a default`);
+                if (f.default !== undefined) {
+                    const want = f.type === 'number' ? 'number' : f.type === 'toggle' ? 'boolean' : 'string';
+                    if (typeof f.default !== want)
+                        p.push(`${at}.default must be a ${want}`);
+                }
+                for (const k of ['min', 'max', 'step'])
+                    if (f[k] !== undefined && typeof f[k] !== 'number')
+                        p.push(`${at}.${k} must be a number`);
+                for (const k of ['help', 'placeholder', 'group'])
+                    if (f[k] !== undefined && typeof f[k] !== 'string')
+                        p.push(`${at}.${k} must be text`);
+                for (const k of ['required', 'serverOnly'])
+                    if (f[k] !== undefined && typeof f[k] !== 'boolean')
+                        p.push(`${at}.${k} must be true or false`);
+            });
+    }
+    if (m.permissions !== undefined) {
+        if (!Array.isArray(m.permissions))
+            p.push('"permissions" must be a list');
+        else
+            m.permissions.forEach((perm, i) => {
+                const ok = perm === 'storage' ||
+                    perm === 'email' ||
+                    (typeof perm === 'string' && /^fetch:(\*|[a-z0-9.-]+(?::\d+)?)$/i.test(perm));
+                if (!ok)
+                    p.push(`permissions[${i}] must be "storage", "email" or "fetch:<host>"`);
+            });
+    }
+    if (p.length)
+        throw new ManifestError(p);
+    return m;
+}
+/** Default values declared by the manifest's settings. */
+export function defaultConfig(manifest) {
+    const out = {};
+    for (const f of manifest.settings ?? [])
+        if (f.default !== undefined)
+            out[f.key] = f.default;
+    return out;
+}
+/** Whether a setting's value may be sent to browsers. */
+export function isPublicSetting(field) {
+    return field.type !== 'secret' && !field.serverOnly;
+}
+/**
+ * Check and normalise values submitted for a plugin's settings.
+ * Returns cleaned values plus per-field messages written for a non-technical reader.
+ */
+export function validateSettings(manifest, input) {
+    const values = {};
+    const errors = {};
+    for (const f of manifest.settings ?? []) {
+        let v = input[f.key];
+        if (typeof v === 'string')
+            v = f.type === 'textarea' || f.type === 'secret' ? v : v.trim();
+        const empty = v === undefined || v === null || v === '';
+        if (empty) {
+            if (f.required)
+                errors[f.key] = `${f.label} is required.`;
+            continue;
+        }
+        switch (f.type) {
+            case 'number': {
+                const n = typeof v === 'number' ? v : Number(v);
+                if (!Number.isFinite(n))
+                    errors[f.key] = `${f.label} must be a number.`;
+                else if (f.min !== undefined && n < f.min)
+                    errors[f.key] = `${f.label} must be at least ${f.min}.`;
+                else if (f.max !== undefined && n > f.max)
+                    errors[f.key] = `${f.label} must be at most ${f.max}.`;
+                else
+                    values[f.key] = n;
+                break;
+            }
+            case 'toggle':
+                if (typeof v !== 'boolean')
+                    errors[f.key] = `${f.label} must be on or off.`;
+                else
+                    values[f.key] = v;
+                break;
+            case 'select':
+                if (typeof v !== 'string' || !f.options?.some((o) => o.value === v))
+                    errors[f.key] = `Choose one of the options for ${f.label}.`;
+                else
+                    values[f.key] = v;
+                break;
+            case 'color':
+                if (typeof v !== 'string' || !/^#[0-9a-fA-F]{6}$/.test(v))
+                    errors[f.key] = `${f.label} must be a colour like #1d4ed8.`;
+                else
+                    values[f.key] = v.toLowerCase();
+                break;
+            case 'url':
+                if (typeof v !== 'string' || !/^https?:\/\/\S+$/i.test(v))
+                    errors[f.key] = `${f.label} must be a web address starting with http:// or https://.`;
+                else
+                    values[f.key] = v;
+                break;
+            case 'email':
+                if (typeof v !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v))
+                    errors[f.key] = `${f.label} must be an email address.`;
+                else
+                    values[f.key] = v;
+                break;
+            default:
+                if (typeof v !== 'string')
+                    errors[f.key] = `${f.label} must be text.`;
+                else if (v.length > 10_000)
+                    errors[f.key] = `${f.label} is too long.`;
+                else
+                    values[f.key] = v;
+        }
+    }
+    return { values, errors };
+}
+export function validateRepositoryIndex(input) {
+    if (!isRecord(input) || !Array.isArray(input.plugins) || !input.plugins.every((x) => typeof x === 'string'))
+        throw new ManifestError(['nextpluggable.json must contain a "plugins" list of directories']);
+    const plugins = input.plugins.map((d) => d.replace(/^\.?\/+/, '').replace(/\/+$/, ''));
+    if (plugins.some((d) => d.split('/').includes('..')))
+        throw new ManifestError(['plugin directories must stay inside the repository']);
+    return {
+        name: typeof input.name === 'string' ? input.name : undefined,
+        description: typeof input.description === 'string' ? input.description : undefined,
+        plugins,
+    };
+}
+export function validateBuild(input) {
+    if (!isRecord(input) || input.buildVersion !== 1)
+        throw new ManifestError(['dist/build.json is missing or was made by an incompatible build tool']);
+    const manifest = validateManifest(input.manifest);
+    const files = {};
+    const rawFiles = isRecord(input.files) ? input.files : {};
+    for (const k of ['client', 'server', 'style']) {
+        const f = rawFiles[k];
+        if (f === undefined)
+            continue;
+        if (!isRecord(f) ||
+            typeof f.path !== 'string' ||
+            f.path.split('/').includes('..') ||
+            f.path.startsWith('/') ||
+            typeof f.sha256 !== 'string' ||
+            !/^[0-9a-f]{64}$/.test(f.sha256) ||
+            typeof f.bytes !== 'number')
+            throw new ManifestError([`dist/build.json has a malformed "${k}" file entry`]);
+        files[k] = { path: f.path, sha256: f.sha256, bytes: f.bytes };
+    }
+    const needsClient = (manifest.pages?.length ?? 0) + (manifest.slots?.length ?? 0) + (manifest.admin?.length ?? 0) > 0;
+    if (needsClient && !files.client)
+        throw new ManifestError(['the plugin declares pages or components but has no built client bundle']);
+    const icon = typeof input.icon === 'string' && input.icon.length <= 64_000 ? input.icon : undefined;
+    return { buildVersion: 1, manifest, icon, files };
+}

package/dist/server.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Server-side API for plugin authors. Everything here is built on web
+ * standards (Request/Response) so the same plugin can run on any host adapter.
+ */
+/** A small key-value store private to the plugin. Values are JSON. */
+export interface PluginStorage {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Keys that start with `prefix` (all keys when omitted), sorted. */
+    list(prefix?: string): Promise<string[]>;
+}
+export interface AdminUser {
+    id: string;
+    name?: string;
+}
+export interface PluginContext<C = Record<string, unknown>> {
+    pluginId: string;
+    /** All settings, including server-only values and decrypted secrets. */
+    config: C;
+    storage: PluginStorage;
+    site: {
+        /** Origin of the site, e.g. `https://example.com`. */
+        url: string;
+    };
+    /** Addresses of this plugin's pages keyed by page id. */
+    paths: Record<string, string>;
+    log(...args: unknown[]): void;
+}
+/**
+ * What a page loader receives. There is deliberately no query string here:
+ * sites cache plugin pages, and a cached page cannot depend on it. Use address
+ * parameters (`/shop/:slug`, `/blog/page/:n`) for content search engines should
+ * see, and `useQuery()` in the browser for filters and searches.
+ */
+export interface PageContext<C = Record<string, unknown>> extends PluginContext<C> {
+    path: string;
+    params: Record<string, string>;
+}
+export interface PageMetadata {
+    title?: string;
+    description?: string;
+    /** Absolute or site-relative canonical URL. Defaults to the page's own address. */
+    canonical?: string;
+    image?: string;
+    noindex?: boolean;
+}
+export interface PageResult<P = Record<string, unknown>> {
+    /** Passed to the page component as `data`. Must be JSON-serialisable. */
+    data?: P;
+    metadata?: PageMetadata;
+    /** schema.org structured data, rendered as JSON-LD. */
+    jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+    /** Respond with the site's 404 page. */
+    notFound?: boolean;
+    /** Redirect to another address. */
+    redirect?: string;
+}
+export interface ApiContext<C = Record<string, unknown>> extends PluginContext<C> {
+    request: Request;
+    /** Path below the plugin's API base, e.g. `/items/42`. */
+    path: string;
+    params: Record<string, string>;
+    /** The signed-in dashboard user, or null for public visitors. */
+    admin: AdminUser | null;
+}
+export type PageLoader<C = Record<string, unknown>> = (ctx: PageContext<C>) => PageResult | Promise<PageResult>;
+export type ApiHandler<C = Record<string, unknown>> = (ctx: ApiContext<C>) => Response | Promise<Response>;
+export interface PluginServer<C = Record<string, unknown>> {
+    /** Server loaders keyed by page id: fetch data and SEO metadata before the page renders. */
+    pages?: Record<string, PageLoader<C>>;
+    /** HTTP endpoints keyed by `"METHOD /path"`, e.g. `"POST /messages"` or `"GET /items/:id"`. */
+    api?: Record<string, ApiHandler<C>>;
+    onInstall?(ctx: PluginContext<C>): void | Promise<void>;
+    onUninstall?(ctx: PluginContext<C>): void | Promise<void>;
+}
+/** Identity helper that gives the server entry full type checking. */
+export declare function definePluginServer<C = Record<string, unknown>>(server: PluginServer<C>): PluginServer<C>;
+/** Restrict an endpoint to the signed-in dashboard user. */
+export declare function adminOnly<C = Record<string, unknown>>(handler: ApiHandler<C>): ApiHandler<C>;
+export declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
+/** Read a JSON request body, returning null when it is missing, malformed or larger than `maxBytes`. */
+export declare function readJson<T = unknown>(request: Request, maxBytes?: number): Promise<T | null>;

package/dist/server.js

@@ -0,0 +1,30 @@
+/**
+ * Server-side API for plugin authors. Everything here is built on web
+ * standards (Request/Response) so the same plugin can run on any host adapter.
+ */
+/** Identity helper that gives the server entry full type checking. */
+export function definePluginServer(server) {
+    return server;
+}
+/** Restrict an endpoint to the signed-in dashboard user. */
+export function adminOnly(handler) {
+    return (ctx) => (ctx.admin ? handler(ctx) : json({ error: 'Sign in to the dashboard to do this.' }, 401));
+}
+export function json(body, status = 200, headers) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8', ...headers },
+    });
+}
+/** Read a JSON request body, returning null when it is missing, malformed or larger than `maxBytes`. */
+export async function readJson(request, maxBytes = 100_000) {
+    try {
+        const text = await request.text();
+        if (text.length > maxBytes)
+            return null;
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@nextpluggable/plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "SDK and build tool for writing NextPluggable plugins",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rohittp0/NextPluggable.git",
+    "directory": "packages/plugin"
+  },
+  "homepage": "https://github.com/rohittp0/NextPluggable#readme",
+  "bugs": "https://github.com/rohittp0/NextPluggable/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.16"
+  },
+  "type": "module",
+  "bin": {
+    "nextpluggable-plugin": "./bin/nextpluggable-plugin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "peerDependencies": {
+    "esbuild": ">=0.21",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "esbuild": "^0.28.2",
+    "react": "^19.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.