@chidchanun/bcp 0.2.13 → 0.2.15

package/packages/server/src/plugins.ts

@@ -0,0 +1,1225 @@
+export type PluginServiceKey<T = unknown> =
+    string | symbol;
+
+export type PluginState =
+    | "registered"
+    | "setting-up"
+    | "ready"
+    | "starting"
+    | "started"
+    | "stopping"
+    | "stopped"
+    | "failed";
+
+export interface PluginConfigSchema<TConfig> {
+    parse(value: unknown): TConfig;
+}
+
+export type PluginConfigParser<TConfig> =
+    | PluginConfigSchema<TConfig>
+    | ((value: unknown) => TConfig);
+
+export interface PluginServiceRegistry {
+    provide<T>(
+        key: PluginServiceKey<T>,
+        value: T,
+        options?: {
+            replace?: boolean;
+        }
+    ): void;
+    get<T>(key: PluginServiceKey<T>): T;
+    optional<T>(
+        key: PluginServiceKey<T>
+    ): T | undefined;
+    has(key: PluginServiceKey): boolean;
+    delete(key: PluginServiceKey): boolean;
+    keys(): PluginServiceKey[];
+}
+
+export type PluginHookHandler<TPayload = unknown> = (
+    payload: TPayload
+) => void | Promise<void>;
+
+export interface PluginHookBus {
+    on<TPayload = unknown>(
+        name: string,
+        handler: PluginHookHandler<TPayload>
+    ): () => void;
+    emit<TPayload = unknown>(
+        name: string,
+        payload: TPayload
+    ): Promise<void>;
+    listenerCount(name: string): number;
+    clear(name?: string): void;
+}
+
+export interface PluginHostView {
+    readonly started: boolean;
+    plugin(name: string): PluginRecord | null;
+    plugins(): PluginRecord[];
+}
+
+export interface PluginContext<TConfig = unknown> {
+    readonly name: string;
+    readonly config: TConfig;
+    readonly services: PluginServiceRegistry;
+    readonly hooks: PluginHookBus;
+    readonly host: PluginHostView;
+}
+
+export interface PluginDefinition<TConfig = unknown> {
+    name: string;
+    version?: string;
+    requires?: readonly string[];
+    optional?: readonly string[];
+    config?: unknown;
+    schema?: PluginConfigParser<TConfig>;
+    setup?(
+        context: PluginContext<TConfig>
+    ): void | Promise<void>;
+    start?(
+        context: PluginContext<TConfig>
+    ): void | Promise<void>;
+    stop?(
+        context: PluginContext<TConfig>
+    ): void | Promise<void>;
+    dispose?(
+        context: PluginContext<TConfig>
+    ): void | Promise<void>;
+}
+
+export interface PluginModule {
+    name: string;
+    plugins: readonly PluginDefinition<any>[];
+}
+
+export interface PluginRecord {
+    name: string;
+    version?: string;
+    state: PluginState;
+    requires: string[];
+    optional: string[];
+    registeredAt: number;
+    setupAt?: number;
+    startedAt?: number;
+    stoppedAt?: number;
+    error?: string;
+}
+
+export interface PluginHostOptions {
+    plugins?: readonly PluginDefinition<any>[];
+    modules?: readonly PluginModule[];
+    configs?: Record<string, unknown>;
+    services?: Iterable<
+        readonly [PluginServiceKey, unknown]
+    >;
+    now?: () => number;
+}
+
+export interface PluginHost
+extends PluginHostView {
+    readonly services: PluginServiceRegistry;
+    readonly hooks: PluginHookBus;
+    use(
+        extension:
+            | PluginDefinition<any>
+            | PluginModule
+    ): PluginHost;
+    resolveOrder(): string[];
+    setup(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    close(): Promise<void>;
+}
+
+interface InternalPlugin {
+    definition: PluginDefinition<any>;
+    record: PluginRecord;
+    context?: PluginContext<any>;
+    disposed: boolean;
+}
+
+export class PluginDependencyError
+extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name =
+            "PluginDependencyError";
+    }
+}
+
+export class PluginLifecycleError
+extends Error {
+    readonly plugin: string;
+    readonly phase: string;
+    readonly cause: unknown;
+
+    constructor(
+        plugin: string,
+        phase: string,
+        cause: unknown
+    ) {
+        super(
+            `BCP Plugins: ${phase} failed for plugin "${plugin}": ${formatError(cause)}`
+        );
+        this.name =
+            "PluginLifecycleError";
+        this.plugin = plugin;
+        this.phase = phase;
+        this.cause = cause;
+    }
+}
+
+export function definePlugin<TConfig = unknown>(
+    definition: PluginDefinition<TConfig>
+): PluginDefinition<TConfig> {
+    validatePluginDefinition(
+        definition
+    );
+    return definition;
+}
+
+export function defineModule(
+    module: PluginModule
+): PluginModule {
+    if (!module || typeof module !== "object") {
+        throw new TypeError(
+            "BCP Plugins: module must be an object."
+        );
+    }
+    normalizeName(
+        module.name,
+        "module name"
+    );
+    if (!Array.isArray(module.plugins)) {
+        throw new TypeError(
+            "BCP Plugins: module plugins must be an array."
+        );
+    }
+    for (const plugin of module.plugins) {
+        validatePluginDefinition(plugin);
+    }
+    return module;
+}
+
+export function createPluginServiceRegistry(
+    initial?: Iterable<
+        readonly [PluginServiceKey, unknown]
+    >
+): PluginServiceRegistry {
+    const values =
+        new Map<PluginServiceKey, unknown>();
+
+    if (initial) {
+        for (const [key, value] of initial) {
+            assertServiceKey(key);
+            if (values.has(key)) {
+                throw new Error(
+                    `BCP Plugins: duplicate initial service ${formatServiceKey(key)}.`
+                );
+            }
+            values.set(key, value);
+        }
+    }
+
+    const registry:
+        PluginServiceRegistry = {
+        provide<T>(
+            key: PluginServiceKey<T>,
+            value: T,
+            options: {
+                replace?: boolean;
+            } = {}
+        ): void {
+            assertServiceKey(key);
+            if (
+                values.has(key) &&
+                !options.replace
+            ) {
+                throw new Error(
+                    `BCP Plugins: service ${formatServiceKey(key)} is already registered.`
+                );
+            }
+            values.set(key, value);
+        },
+
+        get<T>(key: PluginServiceKey<T>): T {
+            assertServiceKey(key);
+            if (!values.has(key)) {
+                throw new Error(
+                    `BCP Plugins: service ${formatServiceKey(key)} is not registered.`
+                );
+            }
+            return values.get(key) as T;
+        },
+
+        optional<T>(
+            key: PluginServiceKey<T>
+        ): T | undefined {
+            assertServiceKey(key);
+            return values.get(key) as
+                T | undefined;
+        },
+
+        has(key: PluginServiceKey): boolean {
+            assertServiceKey(key);
+            return values.has(key);
+        },
+
+        delete(key: PluginServiceKey): boolean {
+            assertServiceKey(key);
+            return values.delete(key);
+        },
+
+        keys(): PluginServiceKey[] {
+            return [
+                ...values.keys(),
+            ];
+        },
+    };
+
+    return registry;
+}
+
+export function createPluginHookBus():
+PluginHookBus {
+    const hooks =
+        new Map<
+            string,
+            Set<PluginHookHandler<any>>
+        >();
+
+    const bus:
+        PluginHookBus = {
+        on<TPayload = unknown>(
+            name: string,
+            handler: PluginHookHandler<TPayload>
+        ): () => void {
+            const normalized =
+                normalizeName(
+                    name,
+                    "hook name"
+                );
+            if (typeof handler !== "function") {
+                throw new TypeError(
+                    "BCP Plugins: hook handler must be a function."
+                );
+            }
+            let group =
+                hooks.get(normalized);
+            if (!group) {
+                group = new Set();
+                hooks.set(
+                    normalized,
+                    group
+                );
+            }
+            group.add(
+                handler as PluginHookHandler<any>
+            );
+            return () => {
+                group?.delete(
+                    handler as PluginHookHandler<any>
+                );
+                if (group?.size === 0) {
+                    hooks.delete(normalized);
+                }
+            };
+        },
+
+        async emit<TPayload = unknown>(
+            name: string,
+            payload: TPayload
+        ): Promise<void> {
+            const normalized =
+                normalizeName(
+                    name,
+                    "hook name"
+                );
+            const group =
+                hooks.get(normalized);
+            if (!group) {
+                return;
+            }
+            for (const handler of [
+                ...group,
+            ]) {
+                await handler(payload);
+            }
+        },
+
+        listenerCount(name: string): number {
+            return hooks.get(
+                normalizeName(
+                    name,
+                    "hook name"
+                )
+            )?.size ?? 0;
+        },
+
+        clear(name?: string): void {
+            if (name === undefined) {
+                hooks.clear();
+                return;
+            }
+            hooks.delete(
+                normalizeName(
+                    name,
+                    "hook name"
+                )
+            );
+        },
+    };
+
+    return bus;
+}
+
+export function createPluginHost(
+    options: PluginHostOptions = {}
+): PluginHost {
+    const now =
+        options.now ?? Date.now;
+    const services =
+        createPluginServiceRegistry(
+            options.services
+        );
+    const hooks =
+        createPluginHookBus();
+    const entries =
+        new Map<string, InternalPlugin>();
+    const configs = {
+        ...(options.configs ?? {}),
+    };
+
+    let setupCompleted = false;
+    let started = false;
+    let closed = false;
+    let lifecycleActive = false;
+    let fatalError:
+        PluginLifecycleError | null =
+        null;
+
+    const host:
+        PluginHost = {
+        services,
+        hooks,
+
+        get started() {
+            return started;
+        },
+
+        use(extension) {
+            assertMutable();
+            if (isPluginModule(extension)) {
+                defineModule(extension);
+                for (const plugin of extension.plugins) {
+                    register(plugin);
+                }
+                return host;
+            }
+            register(extension);
+            return host;
+        },
+
+        resolveOrder() {
+            return resolvePluginOrder(
+                entries
+            );
+        },
+
+        async setup() {
+            assertOpen();
+            assertHealthy();
+            if (setupCompleted) {
+                return;
+            }
+            assertNotActive();
+            lifecycleActive = true;
+            try {
+                const order =
+                    resolvePluginOrder(
+                        entries
+                    );
+                for (const name of order) {
+                    const entry =
+                        requireInternal(name);
+                    if (
+                        entry.record.state !==
+                        "registered"
+                    ) {
+                        continue;
+                    }
+                    entry.record.state =
+                        "setting-up";
+                    try {
+                        const context =
+                            createContext(entry);
+                        entry.context = context;
+                        await entry.definition.setup?.(
+                            context
+                        );
+                        entry.record.state =
+                            "ready";
+                        entry.record.setupAt =
+                            timestamp();
+                    } catch (error) {
+                        markFailed(
+                            entry,
+                            error
+                        );
+                        const lifecycleError =
+                            error instanceof PluginLifecycleError
+                                ? error
+                                : new PluginLifecycleError(
+                                    name,
+                                    "setup",
+                                    error
+                                );
+                        fatalError =
+                            lifecycleError;
+                        await disposePrepared(
+                            order,
+                            name
+                        );
+                        throw lifecycleError;
+                    }
+                }
+                setupCompleted = true;
+            } finally {
+                lifecycleActive = false;
+            }
+        },
+
+        async start() {
+            assertOpen();
+            assertHealthy();
+            if (started) {
+                return;
+            }
+            if (!setupCompleted) {
+                await host.setup();
+            }
+            assertHealthy();
+            assertNotActive();
+            lifecycleActive = true;
+            const order =
+                resolvePluginOrder(
+                    entries
+                );
+            const startedNames:
+                string[] = [];
+            try {
+                for (const name of order) {
+                    const entry =
+                        requireInternal(name);
+                    if (
+                        entry.record.state !== "ready" &&
+                        entry.record.state !== "stopped"
+                    ) {
+                        continue;
+                    }
+                    entry.record.state =
+                        "starting";
+                    try {
+                        await entry.definition.start?.(
+                            requireContext(entry)
+                        );
+                        entry.record.state =
+                            "started";
+                        entry.record.startedAt =
+                            timestamp();
+                        entry.record.error =
+                            undefined;
+                        startedNames.push(name);
+                    } catch (error) {
+                        markFailed(
+                            entry,
+                            error
+                        );
+                        const lifecycleError =
+                            new PluginLifecycleError(
+                                name,
+                                "start",
+                                error
+                            );
+                        fatalError =
+                            lifecycleError;
+                        await stopNames(
+                            [
+                                ...startedNames,
+                            ].reverse()
+                        );
+                        throw lifecycleError;
+                    }
+                }
+                started = true;
+            } finally {
+                lifecycleActive = false;
+            }
+        },
+
+        async stop() {
+            if (closed || !started) {
+                return;
+            }
+            assertNotActive();
+            lifecycleActive = true;
+            try {
+                const errors =
+                    await stopNames(
+                        resolvePluginOrder(
+                            entries
+                        ).reverse()
+                    );
+                started = false;
+                if (errors.length > 0) {
+                    throw new AggregateError(
+                        errors,
+                        "BCP Plugins: one or more plugin stop hooks failed."
+                    );
+                }
+            } finally {
+                lifecycleActive = false;
+            }
+        },
+
+        async close() {
+            if (closed) {
+                return;
+            }
+
+            const errors:
+                unknown[] = [];
+
+            if (started) {
+                try {
+                    await host.stop();
+                } catch (error) {
+                    if (
+                        error instanceof AggregateError
+                    ) {
+                        errors.push(
+                            ...error.errors
+                        );
+                    } else {
+                        errors.push(error);
+                    }
+                }
+            }
+
+            assertNotActive();
+            lifecycleActive = true;
+            try {
+                const order =
+                    resolvePluginOrder(
+                        entries
+                    ).reverse();
+                for (const name of order) {
+                    const entry =
+                        requireInternal(name);
+                    if (
+                        entry.disposed ||
+                        !entry.context
+                    ) {
+                        continue;
+                    }
+                    try {
+                        await entry.definition.dispose?.(
+                            entry.context
+                        );
+                    } catch (error) {
+                        errors.push(
+                            new PluginLifecycleError(
+                                name,
+                                "dispose",
+                                error
+                            )
+                        );
+                    } finally {
+                        entry.disposed = true;
+                    }
+                }
+                hooks.clear();
+                closed = true;
+            } finally {
+                lifecycleActive = false;
+            }
+
+            if (errors.length > 0) {
+                throw new AggregateError(
+                    errors,
+                    "BCP Plugins: one or more plugin shutdown hooks failed."
+                );
+            }
+        },
+
+        plugin(name) {
+            const entry =
+                entries.get(
+                    normalizeName(
+                        name,
+                        "plugin name"
+                    )
+                );
+            return entry
+                ? cloneRecord(
+                    entry.record
+                )
+                : null;
+        },
+
+        plugins() {
+            return [
+                ...entries.values(),
+            ]
+                .map(entry =>
+                    cloneRecord(
+                        entry.record
+                    )
+                )
+                .sort((left, right) =>
+                    left.registeredAt -
+                    right.registeredAt ||
+                    left.name.localeCompare(
+                        right.name
+                    )
+                );
+        },
+    };
+
+    for (const module of options.modules ?? []) {
+        host.use(module);
+    }
+    for (const plugin of options.plugins ?? []) {
+        host.use(plugin);
+    }
+
+    return host;
+
+    function register(
+        definition: PluginDefinition<any>
+    ): void {
+        validatePluginDefinition(
+            definition
+        );
+        const name =
+            normalizeName(
+                definition.name,
+                "plugin name"
+            );
+        if (entries.has(name)) {
+            throw new Error(
+                `BCP Plugins: plugin "${name}" is already registered.`
+            );
+        }
+        const requires =
+            normalizeDependencyList(
+                definition.requires,
+                name,
+                "requires"
+            );
+        const optional =
+            normalizeDependencyList(
+                definition.optional,
+                name,
+                "optional"
+            );
+        entries.set(
+            name,
+            {
+                definition: {
+                    ...definition,
+                    name,
+                    requires,
+                    optional,
+                },
+                record: {
+                    name,
+                    version:
+                        normalizeOptionalVersion(
+                            definition.version
+                        ),
+                    state:
+                        "registered",
+                    requires,
+                    optional,
+                    registeredAt:
+                        timestamp(),
+                },
+                disposed: false,
+            }
+        );
+    }
+
+    function createContext(
+        entry: InternalPlugin
+    ): PluginContext<any> {
+        const rawConfig =
+            Object.prototype.hasOwnProperty.call(
+                configs,
+                entry.record.name
+            )
+                ? configs[entry.record.name]
+                : entry.definition.config;
+        const config =
+            parseConfig(
+                entry.definition.schema,
+                rawConfig,
+                entry.record.name
+            );
+        return {
+            name:
+                entry.record.name,
+            config,
+            services,
+            hooks,
+            host,
+        };
+    }
+
+    async function stopNames(
+        names: readonly string[]
+    ): Promise<unknown[]> {
+        const errors:
+            unknown[] = [];
+        for (const name of names) {
+            const entry =
+                requireInternal(name);
+            if (
+                entry.record.state !==
+                "started"
+            ) {
+                continue;
+            }
+            entry.record.state =
+                "stopping";
+            try {
+                await entry.definition.stop?.(
+                    requireContext(entry)
+                );
+                entry.record.state =
+                    "stopped";
+                entry.record.stoppedAt =
+                    timestamp();
+            } catch (error) {
+                markFailed(
+                    entry,
+                    error
+                );
+                errors.push(
+                    new PluginLifecycleError(
+                        name,
+                        "stop",
+                        error
+                    )
+                );
+            }
+        }
+        return errors;
+    }
+
+    async function disposePrepared(
+        order: readonly string[],
+        failedName: string
+    ): Promise<void> {
+        const index =
+            order.indexOf(failedName);
+        const names =
+            order.slice(
+                0,
+                Math.max(0, index) + 1
+            ).reverse();
+
+        for (const name of names) {
+            const entry =
+                requireInternal(name);
+            if (
+                entry.disposed ||
+                !entry.context
+            ) {
+                continue;
+            }
+            try {
+                await entry.definition.dispose?.(
+                    entry.context
+                );
+            } catch {
+                // Preserve the original setup failure.
+            } finally {
+                entry.disposed = true;
+            }
+        }
+    }
+
+    function requireInternal(
+        name: string
+    ): InternalPlugin {
+        const entry =
+            entries.get(name);
+        if (!entry) {
+            throw new Error(
+                `BCP Plugins: plugin "${name}" is not registered.`
+            );
+        }
+        return entry;
+    }
+
+    function timestamp(): number {
+        const value = now();
+        if (!Number.isFinite(value)) {
+            throw new TypeError(
+                "BCP Plugins: now() must return a finite number."
+            );
+        }
+        return value;
+    }
+
+    function assertOpen(): void {
+        if (closed) {
+            throw new Error(
+                "BCP Plugins: plugin host is closed."
+            );
+        }
+    }
+
+    function assertHealthy(): void {
+        if (fatalError) {
+            throw fatalError;
+        }
+    }
+
+    function assertMutable(): void {
+        assertOpen();
+        if (
+            setupCompleted ||
+            lifecycleActive ||
+            fatalError
+        ) {
+            throw new Error(
+                "BCP Plugins: plugins cannot be registered after setup begins or after a lifecycle failure."
+            );
+        }
+    }
+
+    function assertNotActive(): void {
+        if (lifecycleActive) {
+            throw new Error(
+                "BCP Plugins: another lifecycle transition is already running."
+            );
+        }
+    }
+}
+
+function resolvePluginOrder(
+    entries: Map<string, InternalPlugin>
+): string[] {
+    for (const entry of entries.values()) {
+        for (
+            const dependency
+            of entry.record.requires
+        ) {
+            if (!entries.has(dependency)) {
+                throw new PluginDependencyError(
+                    `BCP Plugins: plugin "${entry.record.name}" requires missing plugin "${dependency}".`
+                );
+            }
+        }
+    }
+
+    const visiting =
+        new Set<string>();
+    const visited =
+        new Set<string>();
+    const order:
+        string[] = [];
+    const stack:
+        string[] = [];
+
+    const visit = (
+        name: string
+    ): void => {
+        if (visited.has(name)) {
+            return;
+        }
+        if (visiting.has(name)) {
+            const start =
+                stack.indexOf(name);
+            const cycle = [
+                ...stack.slice(
+                    Math.max(0, start)
+                ),
+                name,
+            ];
+            throw new PluginDependencyError(
+                `BCP Plugins: dependency cycle detected: ${cycle.join(" -> ")}.`
+            );
+        }
+
+        const entry =
+            entries.get(name);
+        if (!entry) {
+            return;
+        }
+
+        visiting.add(name);
+        stack.push(name);
+
+        for (const dependency of [
+            ...entry.record.requires,
+            ...entry.record.optional.filter(
+                candidate =>
+                    entries.has(candidate)
+            ),
+        ]) {
+            visit(dependency);
+        }
+
+        stack.pop();
+        visiting.delete(name);
+        visited.add(name);
+        order.push(name);
+    };
+
+    for (const name of entries.keys()) {
+        visit(name);
+    }
+
+    return order;
+}
+
+function validatePluginDefinition(
+    definition: PluginDefinition<any>
+): void {
+    if (
+        !definition ||
+        typeof definition !== "object"
+    ) {
+        throw new TypeError(
+            "BCP Plugins: plugin definition must be an object."
+        );
+    }
+    const name =
+        normalizeName(
+            definition.name,
+            "plugin name"
+        );
+    normalizeDependencyList(
+        definition.requires,
+        name,
+        "requires"
+    );
+    normalizeDependencyList(
+        definition.optional,
+        name,
+        "optional"
+    );
+    for (const hook of [
+        "setup",
+        "start",
+        "stop",
+        "dispose",
+    ] as const) {
+        const value =
+            definition[hook];
+        if (
+            value !== undefined &&
+            typeof value !== "function"
+        ) {
+            throw new TypeError(
+                `BCP Plugins: plugin "${name}" ${hook} must be a function.`
+            );
+        }
+    }
+    if (
+        definition.schema !== undefined &&
+        typeof definition.schema !== "function" &&
+        (
+            !definition.schema ||
+            typeof definition.schema.parse !==
+                "function"
+        )
+    ) {
+        throw new TypeError(
+            `BCP Plugins: plugin "${name}" schema must be a parser function or object with parse().`
+        );
+    }
+}
+
+function normalizeDependencyList(
+    value: readonly string[] | undefined,
+    plugin: string,
+    field: string
+): string[] {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new TypeError(
+            `BCP Plugins: plugin "${plugin}" ${field} must be an array.`
+        );
+    }
+    const normalized =
+        value.map(item =>
+            normalizeName(
+                item,
+                `${field} dependency`
+            )
+        );
+    if (
+        new Set(normalized).size !==
+        normalized.length
+    ) {
+        throw new Error(
+            `BCP Plugins: plugin "${plugin}" ${field} contains duplicate dependencies.`
+        );
+    }
+    if (normalized.includes(plugin)) {
+        throw new PluginDependencyError(
+            `BCP Plugins: plugin "${plugin}" cannot depend on itself.`
+        );
+    }
+    return normalized;
+}
+
+function parseConfig<TConfig>(
+    parser: PluginConfigParser<TConfig> | undefined,
+    raw: unknown,
+    plugin: string
+): TConfig {
+    if (!parser) {
+        return raw as TConfig;
+    }
+    try {
+        return typeof parser === "function"
+            ? parser(raw)
+            : parser.parse(raw);
+    } catch (error) {
+        throw new PluginLifecycleError(
+            plugin,
+            "config",
+            error
+        );
+    }
+}
+
+function requireContext(
+    entry: InternalPlugin
+): PluginContext<any> {
+    if (!entry.context) {
+        throw new Error(
+            `BCP Plugins: plugin "${entry.record.name}" has not been set up.`
+        );
+    }
+    return entry.context;
+}
+
+function markFailed(
+    entry: InternalPlugin,
+    error: unknown
+): void {
+    entry.record.state =
+        "failed";
+    entry.record.error =
+        formatError(error);
+}
+
+function cloneRecord(
+    record: PluginRecord
+): PluginRecord {
+    return {
+        ...record,
+        requires: [
+            ...record.requires,
+        ],
+        optional: [
+            ...record.optional,
+        ],
+    };
+}
+
+function isPluginModule(
+    value:
+        | PluginDefinition<any>
+        | PluginModule
+): value is PluginModule {
+    return Boolean(
+        value &&
+        typeof value === "object" &&
+        Array.isArray(
+            (value as PluginModule).plugins
+        )
+    );
+}
+
+function normalizeName(
+    value: unknown,
+    field: string
+): string {
+    const text =
+        String(value ?? "").trim();
+    if (!text) {
+        throw new TypeError(
+            `BCP Plugins: ${field} must be a non-empty string.`
+        );
+    }
+    if (text.length > 200) {
+        throw new TypeError(
+            `BCP Plugins: ${field} must not exceed 200 characters.`
+        );
+    }
+    return text;
+}
+
+function normalizeOptionalVersion(
+    value: string | undefined
+): string | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    return normalizeName(
+        value,
+        "plugin version"
+    );
+}
+
+function assertServiceKey(
+    key: PluginServiceKey
+): void {
+    if (typeof key === "string") {
+        normalizeName(
+            key,
+            "service key"
+        );
+        return;
+    }
+    if (typeof key !== "symbol") {
+        throw new TypeError(
+            "BCP Plugins: service key must be a string or symbol."
+        );
+    }
+}
+
+function formatServiceKey(
+    key: PluginServiceKey
+): string {
+    return typeof key === "symbol"
+        ? String(key)
+        : `"${key}"`;
+}
+
+function formatError(
+    error: unknown
+): string {
+    if (error instanceof Error) {
+        return error.message || error.name;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    try {
+        return JSON.stringify(error) ??
+            String(error);
+    } catch {
+        return String(error);
+    }
+}