@openvcs/sdk 0.2.3 → 0.2.5

package/README.md

@@ -7,7 +7,9 @@
 OpenVCS SDK for npm-based plugin development.
 
 Install this package in plugin projects, scaffold a starter plugin, and package
-plugins into `.ovcsp` bundles.
+plugins into `.ovcsp` bundles. The SDK also exports a Node-only JSON-RPC runtime
+layer and shared protocol/types so plugins do not have to hand-roll stdio
+framing or method dispatch.
 
 ## Install
 
@@ -61,6 +63,35 @@ 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 export a declarative `PluginDefinition` plus an
+`OnPluginStart()` hook that the SDK-owned bootstrap calls for them:
+
+```ts
+import type { PluginModuleDefinition } from '@openvcs/sdk/runtime';
+
+export const PluginDefinition: PluginModuleDefinition = {
+  plugin: {
+    async 'plugin.init'(_params, context) {
+      context.host.info('OpenVCS plugin started');
+      return null;
+    },
+  },
+};
+
+export function OnPluginStart(): void {}
+```
+
+Runtime and protocol imports are exposed as npm subpaths:
+
+```ts
+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, exact-method delegate registration for `vcs.*`, and
+the generated `bin/<module.exec>` bootstrap created by `openvcs build`.
+
 Interactive theme plugin scaffold:
 
 ```bash
@@ -75,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.
@@ -106,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.d.ts

@@ -25,6 +25,7 @@ declare function defaultPluginIdFromDir(targetDir: string): string;
 declare function validatePluginId(pluginId: string): string | undefined;
 declare function createReadlinePromptDriver(output?: NodeJS.WritableStream): PromptDriver;
 declare function collectAnswers({ forceTheme, targetHint }: CollectAnswersOptions, promptDriver?: PromptDriver, output?: NodeJS.WritableStream): Promise<InitAnswers>;
+declare function writeModuleTemplate(answers: InitAnswers): void;
 export declare function runInitCommand(args: string[]): Promise<string>;
 export declare function isUsageError(error: unknown): error is InitCommandError;
 export declare const __private: {
@@ -33,5 +34,6 @@ export declare const __private: {
     defaultPluginIdFromDir: typeof defaultPluginIdFromDir;
     sanitizeIdToken: typeof sanitizeIdToken;
     validatePluginId: typeof validatePluginId;
+    writeModuleTemplate: typeof writeModuleTemplate;
 };
 export {};

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");
 }
@@ -197,8 +197,10 @@ function writeModuleTemplate(answers) {
             dist: "openvcs dist --plugin-dir . --out dist",
             test: "openvcs dist --plugin-dir . --out dist --no-build --no-npm-deps",
         },
-        devDependencies: {
+        dependencies: {
             "@openvcs/sdk": `^${packageJson.version}`,
+        },
+        devDependencies: {
             "@types/node": "^22.0.0",
             typescript: "^5.8.2",
         },
@@ -216,7 +218,7 @@ function writeModuleTemplate(answers) {
         },
         include: ["src/**/*.ts"],
     });
-    writeText(path.join(answers.targetDir, "src", "plugin.ts"), "const message = \"OpenVCS plugin started\";\nprocess.stderr.write(`${message}\\n`);\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);
@@ -229,7 +231,7 @@ function writeThemeTemplate(answers) {
             dist: "openvcs dist --plugin-dir . --out dist",
             test: "openvcs dist --plugin-dir . --out dist --no-build --no-npm-deps",
         },
-        devDependencies: {
+        dependencies: {
             "@openvcs/sdk": `^${packageJson.version}`,
         },
     });
@@ -306,4 +308,5 @@ exports.__private = {
     defaultPluginIdFromDir,
     sanitizeIdToken,
     validatePluginId,
+    writeModuleTemplate,
 };

package/lib/runtime/contracts.d.ts

@@ -0,0 +1,45 @@
+import type { PluginHost, PluginImplements, PluginDelegates, JsonRpcId, JsonRpcRequest, VcsDelegates } from '../types';
+/** Describes the transport endpoints used by the plugin runtime loop. */
+export interface PluginRuntimeTransport {
+    /** Stores the readable stdin-like stream receiving framed messages. */
+    stdin: NodeJS.ReadStream;
+    /** Stores the writable stdout-like stream sending framed messages. */
+    stdout: NodeJS.WritableStream;
+}
+/** Describes the context object passed to every SDK delegate handler. */
+export interface PluginRuntimeContext {
+    /** Stores the active host notification helper. */
+    host: PluginHost;
+    /** Stores the request id currently being processed. */
+    requestId: JsonRpcId;
+    /** Stores the current host method name. */
+    method: string;
+}
+/** Describes the options accepted by `createPluginRuntime`. */
+export interface CreatePluginRuntimeOptions {
+    /** Stores optional plugin lifecycle and settings delegates. */
+    plugin?: PluginDelegates<PluginRuntimeContext>;
+    /** Stores optional VCS method delegates. */
+    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 when runtime starts and begins processing requests. */
+    onStart?: () => void | Promise<void>;
+    /** Called during stop() after pending operations complete. Called with error if shutdown due to processing error. */
+    onShutdown?: (error?: Error) => void | Promise<void>;
+}
+/** Describes one created SDK plugin runtime instance. */
+export interface PluginRuntime {
+    /** Starts listening on stdio for framed JSON-RPC requests. */
+    start(transport?: PluginRuntimeTransport): void;
+    /** Stops the runtime and cleans up pending operations. */
+    stop(): void;
+    /** Consumes one raw stdio chunk and dispatches complete requests. */
+    consumeChunk(chunk: Buffer | string): void;
+    /** Dispatches one already-decoded JSON-RPC request. */
+    dispatchRequest(request: JsonRpcRequest): Promise<void>;
+}

package/lib/runtime/contracts.js

@@ -0,0 +1,4 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/runtime/dispatcher.d.ts

@@ -0,0 +1,16 @@
+import type { JsonRpcId, PluginDelegates, RequestParams } from '../types';
+import type { PluginHost } from '../types';
+import type { CreatePluginRuntimeOptions } from './contracts';
+/** Describes the response emitter used by the dispatcher. */
+export interface DispatcherResponseWriter {
+    /** Emits a JSON-RPC success response. */
+    sendResult<TResult>(id: JsonRpcId, result: TResult): void;
+    /** Emits a JSON-RPC error response. */
+    sendError(id: JsonRpcId, code: number, message: string, data?: unknown): void;
+}
+/** Describes the request handler built by `createRuntimeDispatcher`. */
+export type RuntimeRequestDispatcher = (id: JsonRpcId, method: string, params: RequestParams) => Promise<void>;
+/** Creates the plugin default handlers used when a delegate is omitted. */
+export declare function createDefaultPluginDelegates<TContext>(): Required<Omit<PluginDelegates<TContext>, 'plugin.initialize'>>;
+/** Creates the JSON-RPC dispatcher used by the SDK plugin runtime. */
+export declare function createRuntimeDispatcher(options: CreatePluginRuntimeOptions, host: PluginHost, writer: DispatcherResponseWriter): RuntimeRequestDispatcher;

package/lib/runtime/dispatcher.js

@@ -0,0 +1,133 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultPluginDelegates = createDefaultPluginDelegates;
+exports.createRuntimeDispatcher = createRuntimeDispatcher;
+const types_1 = require("../types");
+const errors_1 = require("./errors");
+/** Creates the plugin default handlers used when a delegate is omitted. */
+function createDefaultPluginDelegates() {
+    return {
+        async 'plugin.init'() {
+            return null;
+        },
+        async 'plugin.deinit'() {
+            return null;
+        },
+        async 'plugin.get_menus'() {
+            return [];
+        },
+        async 'plugin.handle_action'() {
+            return null;
+        },
+        async 'plugin.settings.defaults'() {
+            return [];
+        },
+        async 'plugin.settings.on_load'(params) {
+            return Array.isArray(params.values) ? params.values : [];
+        },
+        async 'plugin.settings.on_apply'() {
+            return null;
+        },
+        async 'plugin.settings.on_save'(params) {
+            return Array.isArray(params.values) ? params.values : [];
+        },
+        async 'plugin.settings.on_reset'() {
+            return null;
+        },
+    };
+}
+/** Creates the JSON-RPC dispatcher used by the SDK plugin runtime. */
+function createRuntimeDispatcher(options, host, writer) {
+    const defaultPluginDelegates = createDefaultPluginDelegates();
+    const pluginDelegates = options.plugin ?? {};
+    const vcsDelegates = options.vcs ?? {};
+    const runtimeImplements = buildRuntimeImplements(options.implements, options.vcs);
+    const timeout = options.timeout;
+    const typedPluginDelegates = pluginDelegates;
+    const typedDefaultPluginDelegates = defaultPluginDelegates;
+    const typedVcsDelegates = vcsDelegates;
+    return async (id, method, params) => {
+        try {
+            if (method === 'plugin.initialize') {
+                const expectedVersion = params.expected_protocol_version;
+                if (typeof expectedVersion === 'number' && expectedVersion !== types_1.PROTOCOL_VERSION) {
+                    writer.sendError(id, types_1.PROTOCOL_VERSION_MISMATCH_CODE, 'protocol version mismatch', {
+                        code: 'protocol-version-mismatch',
+                        message: `host expects protocol ${expectedVersion}, plugin supports ${types_1.PROTOCOL_VERSION}`,
+                    });
+                    return;
+                }
+                const override = pluginDelegates['plugin.initialize']
+                    ? await pluginDelegates['plugin.initialize'](params, {
+                        host,
+                        requestId: id,
+                        method,
+                    })
+                    : {};
+                writer.sendResult(id, {
+                    protocol_version: override.protocol_version ?? types_1.PROTOCOL_VERSION,
+                    implements: {
+                        ...runtimeImplements,
+                        ...override.implements,
+                    },
+                });
+                return;
+            }
+            const handler = typedPluginDelegates[method] ??
+                typedDefaultPluginDelegates[method] ??
+                typedVcsDelegates[method];
+            if (!handler) {
+                throw (0, errors_1.pluginError)('rpc-method-not-found', `method '${method}' is not implemented`);
+            }
+            let result;
+            if (timeout && timeout > 0) {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), timeout);
+                try {
+                    result = await handler(params, {
+                        host,
+                        requestId: id,
+                        method,
+                    });
+                }
+                catch (error) {
+                    clearTimeout(timeoutId);
+                    if (error.name === 'AbortError') {
+                        throw (0, errors_1.pluginError)('request-timeout', `method '${method}' timed out after ${timeout}ms`);
+                    }
+                    throw error;
+                }
+                clearTimeout(timeoutId);
+            }
+            else {
+                result = await handler(params, {
+                    host,
+                    requestId: id,
+                    method,
+                });
+            }
+            writer.sendResult(id, result == null ? null : result);
+        }
+        catch (error) {
+            if ((0, errors_1.isPluginFailure)(error)) {
+                writer.sendError(id, error.code, error.message, error.data);
+                return;
+            }
+            const messageText = error instanceof Error ? error.message : String(error || 'unknown error');
+            host.error(messageText);
+            writer.sendError(id, types_1.PLUGIN_INTERNAL_ERROR_CODE, messageText, {
+                code: 'plugin-internal-error',
+                message: messageText,
+            });
+        }
+    };
+}
+/** Builds the handshake capability flags returned from `plugin.initialize`. */
+function buildRuntimeImplements(overrides, vcsDelegates) {
+    return {
+        plugin: overrides?.plugin ?? true,
+        vcs: overrides?.vcs ?? Boolean(vcsDelegates && Object.keys(vcsDelegates).length > 0),
+    };
+}

package/lib/runtime/errors.d.ts

@@ -0,0 +1,5 @@
+import type { PluginFailure } from '../types';
+/** Builds the host-facing plugin failure payload used for operational errors. */
+export declare function pluginError(code: string, message: string): PluginFailure;
+/** Returns whether the supplied value is a structured plugin failure. */
+export declare function isPluginFailure(value: unknown): value is PluginFailure;

package/lib/runtime/errors.js

@@ -0,0 +1,26 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginError = pluginError;
+exports.isPluginFailure = isPluginFailure;
+const types_1 = require("../types");
+/** Builds the host-facing plugin failure payload used for operational errors. */
+function pluginError(code, message) {
+    return {
+        code: types_1.PLUGIN_FAILURE_CODE,
+        message,
+        data: {
+            code,
+            message,
+        },
+    };
+}
+/** Returns whether the supplied value is a structured plugin failure. */
+function isPluginFailure(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return candidate.code === types_1.PLUGIN_FAILURE_CODE && typeof candidate.message === 'string';
+}

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');
+}