@openvcs/sdk 0.2.4 → 0.2.5

package/README.md

@@ -63,32 +63,34 @@ The generated module template includes TypeScript and Node typings (`@types/node
 Plugin IDs entered during scaffold must not be `.`/`..` and must not contain path
 separators (`/` or `\\`).
 
-Generated module plugins now start with a working SDK runtime entrypoint:
+Generated module plugins now export a declarative `PluginDefinition` plus an
+`OnPluginStart()` hook that the SDK-owned bootstrap calls for them:
 
 ```ts
-import { createPluginRuntime, startPluginRuntime } from '@openvcs/sdk/runtime';
+import type { PluginModuleDefinition } from '@openvcs/sdk/runtime';
 
-const runtime = createPluginRuntime({
+export const PluginDefinition: PluginModuleDefinition = {
   plugin: {
     async 'plugin.init'(_params, context) {
       context.host.info('OpenVCS plugin started');
       return null;
     },
   },
-});
+};
 
-startPluginRuntime(runtime);
+export function OnPluginStart(): void {}
 ```
 
 Runtime and protocol imports are exposed as npm subpaths:
 
 ```ts
-import { createPluginRuntime, pluginError } from '@openvcs/sdk/runtime';
+import { pluginError } from '@openvcs/sdk/runtime';
 import type { PluginDelegates, VcsDelegates } from '@openvcs/sdk/types';
 ```
 
 The runtime handles stdio framing, JSON-RPC request dispatch, host notifications,
-default `plugin.*` handlers, and exact-method delegate registration for `vcs.*`.
+default `plugin.*` handlers, exact-method delegate registration for `vcs.*`, and
+the generated `bin/<module.exec>` bootstrap created by `openvcs build`.
 
 Interactive theme plugin scaffold:
 
@@ -104,8 +106,10 @@ In a generated code plugin folder:
 npm run build
 ```
 
-This runs `openvcs build`, which executes `scripts["build:plugin"]` and verifies
-that `bin/<module.exec>` now exists.
+This runs `openvcs build`, which executes `scripts["build:plugin"]`, expects your
+compiled plugin author module at `bin/plugin.js`, and then generates the SDK-owned
+`bin/<module.exec>` bootstrap that imports `./plugin.js`, applies `PluginDefinition`,
+invokes `OnPluginStart()`, and starts the runtime.
 
 Theme-only plugins can also run `npm run build`; the command exits successfully
 without producing `bin/` output.
@@ -135,6 +139,9 @@ Generated code plugin scripts use this split by default:
 }
 ```
 
+For code plugins, reserve `bin/plugin.js` for the compiled author module and point
+`module.exec` at a different bootstrap filename such as `openvcs-plugin.js`.
+
 `.ovcsp` is a gzip-compressed tar archive (`tar.gz`) that contains a top-level
 `<plugin-id>/` directory with `openvcs.plugin.json` and plugin runtime assets.
 

package/lib/build.d.ts

@@ -20,6 +20,14 @@ export declare function parseBuildArgs(args: string[]): BuildArgs;
 export declare function readManifest(pluginDir: string): ManifestInfo;
 /** Verifies that a declared module entry resolves to a real file under `bin/`. */
 export declare function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined): void;
+/** Returns the compiled plugin module path imported by the generated bootstrap. */
+export declare function authoredPluginModulePath(pluginDir: string): string;
+/** Ensures the plugin's authored module and generated bootstrap paths are compatible. */
+export declare function validateGeneratedBootstrapTargets(pluginDir: string, moduleExec: string | undefined): void;
+/** Renders the generated Node bootstrap that owns runtime startup. */
+export declare function renderGeneratedBootstrap(pluginModuleImportPath: string, isEsm: boolean): string;
+/** Writes the generated SDK-owned module entrypoint under `bin/<module.exec>`. */
+export declare function generateModuleBootstrap(pluginDir: string, moduleExec: string | undefined): void;
 /** Returns whether the plugin repository has a `package.json`. */
 export declare function hasPackageJson(pluginDir: string): boolean;
 /** Runs a command in the given directory with optional verbose logging. */

package/lib/build.js

@@ -7,6 +7,10 @@ exports.buildUsage = buildUsage;
 exports.parseBuildArgs = parseBuildArgs;
 exports.readManifest = readManifest;
 exports.validateDeclaredModuleExec = validateDeclaredModuleExec;
+exports.authoredPluginModulePath = authoredPluginModulePath;
+exports.validateGeneratedBootstrapTargets = validateGeneratedBootstrapTargets;
+exports.renderGeneratedBootstrap = renderGeneratedBootstrap;
+exports.generateModuleBootstrap = generateModuleBootstrap;
 exports.hasPackageJson = hasPackageJson;
 exports.runCommand = runCommand;
 exports.buildPluginAssets = buildPluginAssets;
@@ -14,6 +18,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const node_child_process_1 = require("node:child_process");
 const fs_utils_1 = require("./fs-utils");
+const AUTHORED_PLUGIN_MODULE_BASENAME = "plugin.js";
 /** Returns the npm executable name for the current platform. */
 function npmExecutable() {
     return process.platform === "win32" ? "npm.cmd" : "npm";
@@ -109,6 +114,13 @@ function validateDeclaredModuleExec(pluginDir, moduleExec) {
     if (!moduleExec) {
         return;
     }
+    const targetPath = resolveDeclaredModuleExecPath(pluginDir, moduleExec);
+    if (!fs.existsSync(targetPath) || !fs.lstatSync(targetPath).isFile()) {
+        throw new Error(`module entrypoint not found at ${targetPath}`);
+    }
+}
+/** Resolves `module.exec` to an absolute path under `bin/`, rejecting invalid targets. */
+function resolveDeclaredModuleExecPath(pluginDir, moduleExec) {
     const normalizedExec = moduleExec.trim();
     const lowered = normalizedExec.toLowerCase();
     if (!lowered.endsWith(".js") && !lowered.endsWith(".mjs") && !lowered.endsWith(".cjs")) {
@@ -122,9 +134,75 @@ function validateDeclaredModuleExec(pluginDir, moduleExec) {
     if (!(0, fs_utils_1.isPathInside)(binDir, targetPath) || targetPath === binDir) {
         throw new Error(`manifest module.exec must point to a file under bin/: ${moduleExec}`);
     }
-    if (!fs.existsSync(targetPath) || !fs.lstatSync(targetPath).isFile()) {
-        throw new Error(`module entrypoint not found at ${targetPath}`);
+    return targetPath;
+}
+/** Returns the compiled plugin module path imported by the generated bootstrap. */
+function authoredPluginModulePath(pluginDir) {
+    return path.resolve(pluginDir, "bin", AUTHORED_PLUGIN_MODULE_BASENAME);
+}
+/** Ensures the plugin's authored module and generated bootstrap paths are compatible. */
+function validateGeneratedBootstrapTargets(pluginDir, moduleExec) {
+    if (!moduleExec) {
+        return;
+    }
+    resolveDeclaredModuleExecPath(pluginDir, moduleExec);
+    const normalizedExec = moduleExec.trim().toLowerCase();
+    if (normalizedExec === AUTHORED_PLUGIN_MODULE_BASENAME.toLowerCase()) {
+        throw new Error(`manifest module.exec must not be ${AUTHORED_PLUGIN_MODULE_BASENAME}; SDK reserves bin/${AUTHORED_PLUGIN_MODULE_BASENAME} for the compiled OnPluginStart module`);
+    }
+    const authoredModulePath = authoredPluginModulePath(pluginDir);
+    if (!fs.existsSync(authoredModulePath) || !fs.lstatSync(authoredModulePath).isFile()) {
+        throw new Error(`compiled plugin module not found at ${authoredModulePath}; build:plugin must emit bin/${AUTHORED_PLUGIN_MODULE_BASENAME}`);
+    }
+}
+/** Returns a normalized import specifier from one bin file to another. */
+function relativeBinImport(fromExecPath, toModulePath) {
+    const relativePath = path.relative(path.dirname(fromExecPath), toModulePath).replace(/\\/g, "/");
+    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+/** Validates that a module import path contains only safe characters for code generation. */
+function validateModuleImportPath(importPath) {
+    if (!/^[./a-zA-Z0-9_-]+$/.test(importPath)) {
+        throw new Error(`unsafe module import path: ${importPath}; path must contain only alphanumeric characters, dots, slashes, hyphens, and underscores`);
+    }
+}
+/** Renders the generated Node bootstrap that owns runtime startup. */
+function renderGeneratedBootstrap(pluginModuleImportPath, isEsm) {
+    validateModuleImportPath(pluginModuleImportPath);
+    if (isEsm) {
+        return `#!/usr/bin/env node\n// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\nimport { bootstrapPluginModule } from '@openvcs/sdk/runtime';\n\nawait bootstrapPluginModule({\n  importPluginModule: async () => import('${pluginModuleImportPath}'),\n  modulePath: '${pluginModuleImportPath}',\n});\n`;
+    }
+    return `#!/usr/bin/env node\n// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\n(async () => {\n  const { bootstrapPluginModule } = require('@openvcs/sdk/runtime');\n  await bootstrapPluginModule({\n    importPluginModule: async () => require('${pluginModuleImportPath}'),\n    modulePath: '${pluginModuleImportPath}',\n  });\n})();\n`;
+}
+/** Writes the generated SDK-owned module entrypoint under `bin/<module.exec>`. */
+function generateModuleBootstrap(pluginDir, moduleExec) {
+    if (!moduleExec) {
+        console.debug(`generateModuleBootstrap: no module.exec defined, skipping bootstrap generation for ${pluginDir}`);
+        return;
+    }
+    validateGeneratedBootstrapTargets(pluginDir, moduleExec);
+    const execPath = resolveDeclaredModuleExecPath(pluginDir, moduleExec);
+    const pluginModulePath = authoredPluginModulePath(pluginDir);
+    const pluginModuleImportPath = relativeBinImport(execPath, pluginModulePath);
+    const isEsm = detectEsmMode(pluginDir, moduleExec);
+    fs.mkdirSync(path.dirname(execPath), { recursive: true });
+    fs.writeFileSync(execPath, renderGeneratedBootstrap(pluginModuleImportPath, isEsm), "utf8");
+}
+/** Detects whether the plugin runs in ESM mode based on package.json or file extension. */
+function detectEsmMode(pluginDir, moduleExec) {
+    const packageJsonPath = path.join(pluginDir, "package.json");
+    if (fs.existsSync(packageJsonPath) && fs.lstatSync(packageJsonPath).isFile()) {
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+            if (packageJson.type === "module") {
+                return true;
+            }
+        }
+        catch {
+            // Ignore JSON parse errors
+        }
     }
+    return moduleExec.trim().endsWith(".mjs");
 }
 /** Returns whether the plugin repository has a `package.json`. */
 function hasPackageJson(pluginDir) {
@@ -183,6 +261,7 @@ function buildPluginAssets(parsedArgs) {
         throw new Error(`code plugins must define scripts[\"build:plugin\"] in ${path.join(parsedArgs.pluginDir, "package.json")}`);
     }
     runCommand(npmExecutable(), ["run", "build:plugin"], parsedArgs.pluginDir, parsedArgs.verbose);
+    generateModuleBootstrap(parsedArgs.pluginDir, manifest.moduleExec);
     validateDeclaredModuleExec(parsedArgs.pluginDir, manifest.moduleExec);
     return manifest;
 }

package/lib/dist.js

@@ -195,6 +195,7 @@ async function bundlePlugin(parsedArgs) {
     if (!moduleExec && !hasThemes && !entry) {
         throw new Error("manifest has no module.exec, entry, or themes/");
     }
+    (0, build_1.validateGeneratedBootstrapTargets)(pluginDir, moduleExec);
     (0, build_1.validateDeclaredModuleExec)(pluginDir, moduleExec);
     (0, fs_utils_1.ensureDirectory)(outDir);
     const stagingRoot = uniqueStagingDir(outDir);

package/lib/init.js

@@ -180,7 +180,7 @@ function writeCommonFiles(answers) {
         name: answers.pluginName,
         version: answers.pluginVersion,
         default_enabled: answers.defaultEnabled,
-        ...(answers.kind === "module" ? { module: { exec: "plugin.js" } } : {}),
+        ...(answers.kind === "module" ? { module: { exec: "openvcs-plugin.js" } } : {}),
     });
     writeText(path.join(answers.targetDir, ".gitignore"), "node_modules/\ndist/\n");
 }
@@ -218,7 +218,7 @@ function writeModuleTemplate(answers) {
         },
         include: ["src/**/*.ts"],
     });
-    writeText(path.join(answers.targetDir, "src", "plugin.ts"), "// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\nimport { createPluginRuntime, startPluginRuntime } from '@openvcs/sdk/runtime';\n\nconst runtime = createPluginRuntime({\n  plugin: {\n    async 'plugin.init'(_params, context) {\n      context.host.info('OpenVCS plugin started');\n      return null;\n    },\n  },\n});\n\nstartPluginRuntime(runtime);\n");
+    writeText(path.join(answers.targetDir, "src", "plugin.ts"), "// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\nimport type { PluginModuleDefinition } from '@openvcs/sdk/runtime';\n\nexport const PluginDefinition: PluginModuleDefinition = {\n  plugin: {\n    async 'plugin.init'(_params, context) {\n      context.host.info('OpenVCS plugin started');\n      return null;\n    },\n  },\n};\n\n/** Runs plugin startup work before the generated runtime begins processing requests. */\nexport function OnPluginStart(): void {}\n");
 }
 function writeThemeTemplate(answers) {
     writeCommonFiles(answers);

package/lib/runtime/factory.d.ts

@@ -0,0 +1,3 @@
+import type { CreatePluginRuntimeOptions, PluginRuntime } from './contracts';
+/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
+export declare function createPluginRuntime(options?: CreatePluginRuntimeOptions): PluginRuntime;

package/lib/runtime/factory.js

@@ -0,0 +1,153 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPluginRuntime = createPluginRuntime;
+const dispatcher_1 = require("./dispatcher");
+const host_1 = require("./host");
+const transport_1 = require("./transport");
+/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
+function createPluginRuntime(options = {}) {
+    let buffer = Buffer.alloc(0);
+    let processing = Promise.resolve();
+    let started = false;
+    let currentTransport = null;
+    let chunkLock = Promise.resolve();
+    const runtime = {
+        start(transport = defaultTransport()) {
+            if (started) {
+                return;
+            }
+            started = true;
+            currentTransport = transport;
+            transport.stdin.on('data', (chunk) => {
+                runtime.consumeChunk(chunk);
+            });
+            transport.stdin.on('error', () => {
+                process.exit(1);
+            });
+            options.onStart?.();
+        },
+        stop() {
+            if (!started) {
+                return;
+            }
+            started = false;
+            processing = processing
+                .catch(async (error) => {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`[runtime] shutdown error: ${errorMessage}`);
+                const err = error instanceof Error ? error : new Error(errorMessage);
+                await options.onShutdown?.(err);
+            })
+                .then(async () => {
+                await options.onShutdown?.();
+            });
+            currentTransport = null;
+        },
+        consumeChunk(chunk) {
+            if (!started) {
+                return;
+            }
+            const lock = chunkLock.then(() => {
+                buffer = Buffer.concat([buffer, normalizeChunk(chunk)]);
+                const parsed = (0, transport_1.parseFramedMessages)(buffer);
+                buffer = parsed.remainder;
+                for (const request of parsed.messages) {
+                    processing = processing
+                        .then(async () => {
+                        await runtime.dispatchRequest(request);
+                    })
+                        .catch((error) => {
+                        const message = error instanceof Error ? error.message : String(error || 'unknown plugin processing error');
+                        const host = createRuntimeHost(currentTransport, options.logTarget);
+                        host.error(message);
+                    });
+                }
+            });
+            chunkLock = lock;
+        },
+        async dispatchRequest(request) {
+            const id = request.id;
+            const host = createRuntimeHost(currentTransport, options.logTarget);
+            const method = asTrimmedString(request.method);
+            const validationErrors = [];
+            if (!method)
+                validationErrors.push('missing method');
+            if (typeof id !== 'number' && typeof id !== 'string')
+                validationErrors.push(`invalid id type: ${typeof id}`);
+            if (validationErrors.length > 0) {
+                host.error(`invalid request: ${validationErrors.join(', ')}`);
+                return;
+            }
+            const dispatcher = (0, dispatcher_1.createRuntimeDispatcher)(options, host, {
+                async sendResult(requestId, result) {
+                    await sendMessage(currentTransport, {
+                        jsonrpc: '2.0',
+                        id: requestId,
+                        result,
+                    });
+                },
+                async sendError(requestId, code, message, data) {
+                    await sendMessage(currentTransport, {
+                        jsonrpc: '2.0',
+                        id: requestId,
+                        error: {
+                            code,
+                            message,
+                            ...(data == null ? {} : { data }),
+                        },
+                    });
+                },
+            });
+            const methodName = method;
+            const params = asRecord(request.params) ?? {};
+            const requestId = id;
+            await dispatcher(requestId, methodName, params);
+        },
+    };
+    return runtime;
+}
+/** Returns the default stdio transport used by the runtime. */
+function defaultTransport() {
+    return {
+        stdin: process.stdin,
+        stdout: process.stdout,
+    };
+}
+/** Sends one JSON-RPC response or notification through the active transport. */
+async function sendMessage(transport, value) {
+    await (0, transport_1.writeFramedMessage)((transport ?? defaultTransport()).stdout, value);
+}
+/** Builds the host helper for the currently active transport. */
+function createRuntimeHost(transport, logTarget) {
+    return (0, host_1.createHost)(async (method, params) => {
+        await sendMessage(transport, {
+            jsonrpc: '2.0',
+            method,
+            params,
+        });
+    }, { logTarget });
+}
+/** Type guard that returns true if the value is a valid RequestParams object. */
+function isRequestParams(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    return true;
+}
+/** Coerces unknown request method values into trimmed strings. Returns null for non-strings. */
+function asTrimmedString(value) {
+    return typeof value === 'string' ? value.trim() : null;
+}
+/** Coerces unknown params to a Record, returning null for invalid input. */
+function asRecord(value) {
+    if (isRequestParams(value)) {
+        return value;
+    }
+    return null;
+}
+/** Normalizes incoming data chunks to UTF-8 buffers. */
+function normalizeChunk(chunk) {
+    return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+}

package/lib/runtime/index.d.ts

@@ -1,9 +1,10 @@
-import type { CreatePluginRuntimeOptions, PluginRuntime, PluginRuntimeTransport } from './contracts';
+import type { PluginRuntime, PluginRuntimeTransport } from './contracts';
 export type { CreatePluginRuntimeOptions, PluginRuntime, PluginRuntimeContext, PluginRuntimeTransport, } from './contracts';
-export { createDefaultPluginDelegates } from './dispatcher';
+export type { BootstrapPluginModuleOptions, OnPluginStartHandler, PluginBootstrapModule, PluginModuleDefinition, } from './registration';
+export { createDefaultPluginDelegates, createRuntimeDispatcher } from './dispatcher';
 export { isPluginFailure, pluginError } from './errors';
+export { createPluginRuntime } from './factory';
 export { createHost } from './host';
-/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
-export declare function createPluginRuntime(options?: CreatePluginRuntimeOptions): PluginRuntime;
+export { bootstrapPluginModule, createRegisteredPluginRuntime, } from './registration';
 /** Starts a previously created plugin runtime on process stdio. */
 export declare function startPluginRuntime(runtime: PluginRuntime, transport?: PluginRuntimeTransport): void;

package/lib/runtime/index.js

@@ -2,165 +2,22 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createHost = exports.pluginError = exports.isPluginFailure = exports.createDefaultPluginDelegates = void 0;
-exports.createPluginRuntime = createPluginRuntime;
+exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
 exports.startPluginRuntime = startPluginRuntime;
-const dispatcher_1 = require("./dispatcher");
-const host_1 = require("./host");
-const transport_1 = require("./transport");
-var dispatcher_2 = require("./dispatcher");
-Object.defineProperty(exports, "createDefaultPluginDelegates", { enumerable: true, get: function () { return dispatcher_2.createDefaultPluginDelegates; } });
+var dispatcher_1 = require("./dispatcher");
+Object.defineProperty(exports, "createDefaultPluginDelegates", { enumerable: true, get: function () { return dispatcher_1.createDefaultPluginDelegates; } });
+Object.defineProperty(exports, "createRuntimeDispatcher", { enumerable: true, get: function () { return dispatcher_1.createRuntimeDispatcher; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "isPluginFailure", { enumerable: true, get: function () { return errors_1.isPluginFailure; } });
 Object.defineProperty(exports, "pluginError", { enumerable: true, get: function () { return errors_1.pluginError; } });
-var host_2 = require("./host");
-Object.defineProperty(exports, "createHost", { enumerable: true, get: function () { return host_2.createHost; } });
-/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
-function createPluginRuntime(options = {}) {
-    let buffer = Buffer.alloc(0);
-    let processing = Promise.resolve();
-    let started = false;
-    let currentTransport = null;
-    let chunkLock = Promise.resolve();
-    const runtime = {
-        start(transport = defaultTransport()) {
-            if (started) {
-                return;
-            }
-            started = true;
-            currentTransport = transport;
-            transport.stdin.on('data', (chunk) => {
-                runtime.consumeChunk(chunk);
-            });
-            transport.stdin.on('error', () => {
-                process.exit(1);
-            });
-            options.onStart?.();
-        },
-        stop() {
-            if (!started) {
-                return;
-            }
-            started = false;
-            processing = processing
-                .catch(async (error) => {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                console.error(`[runtime] shutdown error: ${errorMessage}`);
-                const err = error instanceof Error ? error : new Error(errorMessage);
-                await options.onShutdown?.(err);
-            })
-                .then(async () => {
-                await options.onShutdown?.();
-            });
-            currentTransport = null;
-        },
-        consumeChunk(chunk) {
-            if (!started) {
-                return;
-            }
-            const lock = chunkLock.then(() => {
-                buffer = Buffer.concat([buffer, normalizeChunk(chunk)]);
-                const parsed = (0, transport_1.parseFramedMessages)(buffer);
-                buffer = parsed.remainder;
-                for (const request of parsed.messages) {
-                    processing = processing
-                        .then(async () => {
-                        await runtime.dispatchRequest(request);
-                    })
-                        .catch((error) => {
-                        const message = error instanceof Error ? error.message : String(error || 'unknown plugin processing error');
-                        const host = createRuntimeHost(currentTransport, options.logTarget);
-                        host.error(message);
-                    });
-                }
-            });
-            chunkLock = lock;
-        },
-        async dispatchRequest(request) {
-            const id = request.id;
-            const host = createRuntimeHost(currentTransport, options.logTarget);
-            const method = asTrimmedString(request.method);
-            const validationErrors = [];
-            if (!method)
-                validationErrors.push('missing method');
-            if (typeof id !== 'number' && typeof id !== 'string')
-                validationErrors.push(`invalid id type: ${typeof id}`);
-            if (validationErrors.length > 0) {
-                host.error(`invalid request: ${validationErrors.join(', ')}`);
-                return;
-            }
-            const dispatcher = (0, dispatcher_1.createRuntimeDispatcher)(options, host, {
-                async sendResult(requestId, result) {
-                    await sendMessage(currentTransport, {
-                        jsonrpc: '2.0',
-                        id: requestId,
-                        result,
-                    });
-                },
-                async sendError(requestId, code, message, data) {
-                    await sendMessage(currentTransport, {
-                        jsonrpc: '2.0',
-                        id: requestId,
-                        error: {
-                            code,
-                            message,
-                            ...(data == null ? {} : { data }),
-                        },
-                    });
-                },
-            });
-            const methodName = method;
-            const params = asRecord(request.params) ?? {};
-            const requestId = id;
-            await dispatcher(requestId, methodName, params);
-        },
-    };
-    return runtime;
-}
+var factory_1 = require("./factory");
+Object.defineProperty(exports, "createPluginRuntime", { enumerable: true, get: function () { return factory_1.createPluginRuntime; } });
+var host_1 = require("./host");
+Object.defineProperty(exports, "createHost", { enumerable: true, get: function () { return host_1.createHost; } });
+var registration_1 = require("./registration");
+Object.defineProperty(exports, "bootstrapPluginModule", { enumerable: true, get: function () { return registration_1.bootstrapPluginModule; } });
+Object.defineProperty(exports, "createRegisteredPluginRuntime", { enumerable: true, get: function () { return registration_1.createRegisteredPluginRuntime; } });
 /** Starts a previously created plugin runtime on process stdio. */
 function startPluginRuntime(runtime, transport) {
     runtime.start(transport);
 }
-/** Returns the default stdio transport used by the runtime. */
-function defaultTransport() {
-    return {
-        stdin: process.stdin,
-        stdout: process.stdout,
-    };
-}
-/** Sends one JSON-RPC response or notification through the active transport. */
-async function sendMessage(transport, value) {
-    await (0, transport_1.writeFramedMessage)((transport ?? defaultTransport()).stdout, value);
-}
-/** Builds the host helper for the currently active transport. */
-function createRuntimeHost(transport, logTarget) {
-    return (0, host_1.createHost)(async (method, params) => {
-        await sendMessage(transport, {
-            jsonrpc: '2.0',
-            method,
-            params,
-        });
-    }, { logTarget });
-}
-/** Type guard that returns true if the value is a valid RequestParams object. */
-function isRequestParams(value) {
-    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
-        return false;
-    }
-    return true;
-}
-/** Coerces unknown request method values into trimmed strings. Returns null for non-strings. */
-function asTrimmedString(value) {
-    return typeof value === 'string' ? value.trim() : null;
-}
-/** Coerces unknown params to a Record, returning null for invalid input. */
-function asRecord(value) {
-    if (isRequestParams(value)) {
-        return value;
-    }
-    return null;
-}
-/** Normalizes incoming data chunks to UTF-8 buffers. */
-function normalizeChunk(chunk) {
-    return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
-}

package/lib/runtime/registration.d.ts

@@ -0,0 +1,39 @@
+import type { PluginDelegates, PluginImplements, VcsDelegates } from '../types';
+import type { PluginRuntime, PluginRuntimeContext, PluginRuntimeTransport } from './contracts';
+/** Describes the plugin module startup hook invoked by the generated bootstrap. */
+export type OnPluginStartHandler = () => void | Promise<void>;
+/** Describes runtime-wide options applied by the generated bootstrap. */
+export interface PluginModuleDefinition {
+    /** Stores optional `plugin.*` delegates contributed by the plugin module. */
+    plugin?: PluginDelegates<PluginRuntimeContext>;
+    /** Stores optional `vcs.*` delegates contributed by the plugin module. */
+    vcs?: VcsDelegates<PluginRuntimeContext>;
+    /** Stores optional capability overrides for `plugin.initialize`. */
+    implements?: Partial<PluginImplements>;
+    /** Stores the `host.log` target emitted by the runtime. */
+    logTarget?: string;
+    /** Stores the timeout in milliseconds for request handlers. */
+    timeout?: number;
+    /** Called during stop() after pending operations complete. */
+    onShutdown?: (error?: Error) => void | Promise<void>;
+}
+/** Describes one imported plugin module consumed by the generated bootstrap. */
+export interface PluginBootstrapModule {
+    /** Stores the plugin author's declarative runtime definition. */
+    PluginDefinition?: PluginModuleDefinition;
+    /** Stores the plugin author's startup hook. */
+    OnPluginStart?: OnPluginStartHandler;
+}
+/** Describes the generated bootstrap inputs used to import and start a plugin. */
+export interface BootstrapPluginModuleOptions {
+    /** Imports the plugin author's compiled runtime module. */
+    importPluginModule: () => Promise<PluginBootstrapModule>;
+    /** Stores the plugin module path for error messages. */
+    modulePath: string;
+    /** Overrides the transport used by the runtime loop. */
+    transport?: PluginRuntimeTransport;
+}
+/** Creates a runtime from one declarative plugin module definition. */
+export declare function createRegisteredPluginRuntime(definition?: PluginModuleDefinition): PluginRuntime;
+/** Imports the author module, applies its definition, runs `OnPluginStart`, and starts the runtime loop. */
+export declare function bootstrapPluginModule(options: BootstrapPluginModuleOptions): Promise<PluginRuntime>;

package/lib/runtime/registration.js

@@ -0,0 +1,37 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRegisteredPluginRuntime = createRegisteredPluginRuntime;
+exports.bootstrapPluginModule = bootstrapPluginModule;
+const factory_1 = require("./factory");
+/** Creates a runtime from one declarative plugin module definition. */
+function createRegisteredPluginRuntime(definition = {}) {
+    const options = {
+        plugin: definition.plugin,
+        vcs: definition.vcs,
+        implements: definition.implements,
+        logTarget: definition.logTarget,
+        timeout: definition.timeout,
+        onShutdown: definition.onShutdown,
+    };
+    return (0, factory_1.createPluginRuntime)(options);
+}
+/** Imports the author module, applies its definition, runs `OnPluginStart`, and starts the runtime loop. */
+async function bootstrapPluginModule(options) {
+    const pluginModule = await options.importPluginModule();
+    const onPluginStart = pluginModule.OnPluginStart;
+    if (typeof onPluginStart !== 'function') {
+        throw new Error(`plugin module '${options.modulePath}' must export OnPluginStart()`);
+    }
+    try {
+        await onPluginStart();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`plugin startup failed: ${message}`);
+    }
+    const runtime = createRegisteredPluginRuntime(pluginModule.PluginDefinition);
+    runtime.start(options.transport);
+    return runtime;
+}