@openvcs/sdk 0.2.2 → 0.2.4

package/lib/dist.js

@@ -6,21 +6,19 @@ exports.parseDistArgs = parseDistArgs;
 exports.bundlePlugin = bundlePlugin;
 const fs = require("node:fs");
 const path = require("node:path");
-const node_child_process_1 = require("node:child_process");
 const tar = require("tar");
+const build_1 = require("./build");
 const fs_utils_1 = require("./fs-utils");
 const ICON_EXTENSIONS = ["png", "jpg", "jpeg", "webp", "avif", "svg"];
-function npmExecutable() {
-    return process.platform === "win32" ? "npm.cmd" : "npm";
-}
 function distUsage(commandName = "openvcs") {
-    return `${commandName} dist [args]\n\n  --plugin-dir <path>   Plugin repository root (contains openvcs.plugin.json)\n  --out <path>          Output directory (default: ./dist)\n  --no-npm-deps         Disable npm dependency bundling (enabled by default)\n  -V, --verbose         Enable verbose output\n`;
+    return `${commandName} dist [args]\n\n  --plugin-dir <path>   Plugin repository root (contains openvcs.plugin.json)\n  --out <path>          Output directory (default: ./dist)\n  --no-build            Skip the plugin build step before packaging\n  --no-npm-deps         Disable npm dependency bundling (enabled by default)\n  -V, --verbose         Enable verbose output\n`;
 }
 function parseDistArgs(args) {
     let pluginDir = process.cwd();
     let outDir = "dist";
     let verbose = false;
     let noNpmDeps = false;
+    let noBuild = false;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === "--plugin-dir") {
@@ -43,6 +41,10 @@ function parseDistArgs(args) {
             noNpmDeps = true;
             continue;
         }
+        if (arg === "--no-build") {
+            noBuild = true;
+            continue;
+        }
         if (arg === "-V" || arg === "--verbose") {
             verbose = true;
             continue;
@@ -59,109 +61,44 @@ function parseDistArgs(args) {
         outDir: path.resolve(outDir),
         verbose,
         noNpmDeps,
+        noBuild,
     };
 }
-function readManifest(pluginDir) {
-    const manifestPath = path.join(pluginDir, "openvcs.plugin.json");
-    let manifestRaw;
-    let manifestFd;
-    let manifest;
-    try {
-        manifestFd = fs.openSync(manifestPath, "r");
-        const manifestStat = fs.fstatSync(manifestFd);
-        if (!manifestStat.isFile()) {
-            throw new Error(`missing openvcs.plugin.json at ${manifestPath}`);
-        }
-        manifestRaw = fs.readFileSync(manifestFd, "utf8");
-    }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            throw new Error(`missing openvcs.plugin.json at ${manifestPath}`);
-        }
-        throw error;
-    }
-    finally {
-        if (typeof manifestFd === "number") {
-            fs.closeSync(manifestFd);
-        }
-    }
-    try {
-        manifest = JSON.parse(manifestRaw);
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new Error(`parse ${manifestPath}: ${detail}`);
-    }
-    const pluginId = typeof manifest.id === "string"
-        ? manifest.id.trim()
-        : "";
-    if (!pluginId) {
-        throw new Error(`manifest ${manifestPath} is missing a string 'id'`);
-    }
-    if (pluginId === "." || pluginId === ".." || pluginId.includes("/") || pluginId.includes("\\")) {
-        throw new Error(`manifest id must not contain path separators: ${pluginId}`);
-    }
-    const moduleValue = manifest.module;
-    const moduleExec = typeof moduleValue?.exec === "string" ? moduleValue.exec.trim() : undefined;
-    return {
-        pluginId,
-        moduleExec,
-        manifestPath,
-    };
-}
-function validateDeclaredModuleExec(pluginDir, moduleExec) {
-    if (!moduleExec) {
-        return;
-    }
-    const normalizedExec = moduleExec.trim();
-    const lowered = normalizedExec.toLowerCase();
-    if (!lowered.endsWith(".js") && !lowered.endsWith(".mjs") && !lowered.endsWith(".cjs")) {
-        throw new Error(`manifest exec must end with .js/.mjs/.cjs (Node runtime): ${moduleExec}`);
+function validateManifestEntry(pluginDir, entry) {
+    const normalized = entry.trim();
+    if (path.isAbsolute(normalized)) {
+        throw new Error(`manifest entry must be a relative path: ${entry}`);
     }
-    if (path.isAbsolute(normalizedExec)) {
-        throw new Error(`manifest module.exec must be a relative path under bin/: ${moduleExec}`);
-    }
-    const binDir = path.resolve(pluginDir, "bin");
-    const targetPath = path.resolve(binDir, normalizedExec);
-    if (!(0, fs_utils_1.isPathInside)(binDir, targetPath) || targetPath === binDir) {
-        throw new Error(`manifest module.exec must point to a file under bin/: ${moduleExec}`);
+    const targetPath = path.resolve(pluginDir, normalized);
+    const pluginDirResolved = path.resolve(pluginDir);
+    if (!(0, fs_utils_1.isPathInside)(pluginDirResolved, targetPath) || targetPath === pluginDirResolved) {
+        throw new Error(`manifest entry must point to a file under the plugin directory: ${entry}`);
     }
     if (!fs.existsSync(targetPath) || !fs.lstatSync(targetPath).isFile()) {
-        throw new Error(`module entrypoint not found at ${targetPath}`);
+        throw new Error(`manifest entry file not found: ${entry}`);
     }
 }
-function hasPackageJson(pluginDir) {
-    const packageJsonPath = path.join(pluginDir, "package.json");
-    return fs.existsSync(packageJsonPath) && fs.lstatSync(packageJsonPath).isFile();
+function copyEntryDirectory(pluginDir, bundleDir, entry) {
+    const normalized = entry.trim();
+    const entryDir = path.dirname(normalized);
+    const sourceDir = path.join(pluginDir, entryDir);
+    const destDir = path.join(bundleDir, entryDir);
+    (0, fs_utils_1.copyDirectoryRecursiveStrict)(sourceDir, destDir);
 }
-function runCommand(program, args, cwd, verbose) {
-    if (verbose) {
-        process.stderr.write(`Running command in ${cwd}: ${program} ${args.join(" ")}\n`);
-    }
-    const result = (0, node_child_process_1.spawnSync)(program, args, {
-        cwd,
-        stdio: ["ignore", verbose ? "inherit" : "ignore", "inherit"],
-    });
-    if (result.error) {
-        throw new Error(`failed to spawn '${program}' in ${cwd}: ${result.error.message}`);
-    }
-    if (result.status === 0) {
-        return;
-    }
-    throw new Error(`command failed (${program} ${args.join(" ")}), exit code ${result.status}`);
-}
-function ensurePackageLock(pluginDir, verbose) {
-    if (!hasPackageJson(pluginDir)) {
+function ensurePackageLock(pluginDir, bundleDir, verbose) {
+    if (!(0, build_1.hasPackageJson)(pluginDir)) {
         return;
     }
     const lockPath = path.join(pluginDir, "package-lock.json");
     if (fs.existsSync(lockPath) && fs.lstatSync(lockPath).isFile()) {
         return;
     }
+    const packageJsonPath = path.join(pluginDir, "package.json");
+    (0, fs_utils_1.copyFileStrict)(packageJsonPath, path.join(bundleDir, "package.json"));
     if (verbose) {
-        process.stderr.write(`Generating package-lock.json in ${pluginDir}\n`);
+        process.stderr.write(`Generating package-lock.json in staging\n`);
     }
-    runCommand(npmExecutable(), ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"], pluginDir, verbose);
+    (0, build_1.runCommand)((0, build_1.npmExecutable)(), ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"], bundleDir, verbose);
 }
 function copyNpmFilesToStaging(pluginDir, bundleDir) {
     const packageJsonPath = path.join(pluginDir, "package.json");
@@ -169,11 +106,14 @@ function copyNpmFilesToStaging(pluginDir, bundleDir) {
     if (!fs.existsSync(packageJsonPath) || !fs.lstatSync(packageJsonPath).isFile()) {
         throw new Error(`missing package.json at ${packageJsonPath}`);
     }
-    if (!fs.existsSync(lockPath) || !fs.lstatSync(lockPath).isFile()) {
-        throw new Error(`missing package-lock.json at ${lockPath}`);
-    }
     (0, fs_utils_1.copyFileStrict)(packageJsonPath, path.join(bundleDir, "package.json"));
-    (0, fs_utils_1.copyFileStrict)(lockPath, path.join(bundleDir, "package-lock.json"));
+    const stagedLockPath = path.join(bundleDir, "package-lock.json");
+    if (fs.existsSync(stagedLockPath) && fs.lstatSync(stagedLockPath).isFile()) {
+        return;
+    }
+    if (fs.existsSync(lockPath) && fs.lstatSync(lockPath).isFile()) {
+        (0, fs_utils_1.copyFileStrict)(lockPath, path.join(bundleDir, "package-lock.json"));
+    }
 }
 function rejectNativeAddonsRecursive(dirPath) {
     const entries = fs.readdirSync(dirPath, { withFileTypes: true });
@@ -197,7 +137,7 @@ function rejectNativeAddonsRecursive(dirPath) {
 }
 function installNpmDependencies(pluginDir, bundleDir, verbose) {
     copyNpmFilesToStaging(pluginDir, bundleDir);
-    runCommand(npmExecutable(), ["ci", "--omit=dev", "--ignore-scripts", "--no-bin-links", "--no-audit", "--no-fund"], bundleDir, verbose);
+    (0, build_1.runCommand)((0, build_1.npmExecutable)(), ["ci", "--omit=dev", "--ignore-scripts", "--no-bin-links", "--no-audit", "--no-fund"], bundleDir, verbose);
     const nodeModulesPath = path.join(bundleDir, "node_modules");
     if (!fs.existsSync(nodeModulesPath)) {
         return;
@@ -208,14 +148,19 @@ function installNpmDependencies(pluginDir, bundleDir, verbose) {
     rejectNativeAddonsRecursive(nodeModulesPath);
 }
 function copyIcon(pluginDir, bundleDir) {
-    for (const extension of ICON_EXTENSIONS) {
-        const fileName = `icon.${extension}`;
-        const sourcePath = path.join(pluginDir, fileName);
-        if (!fs.existsSync(sourcePath)) {
-            continue;
+    const entries = fs.readdirSync(pluginDir, { withFileTypes: true });
+    const iconEntries = entries.filter((e) => {
+        if (!e.isFile())
+            return false;
+        const name = e.name.toLowerCase();
+        return name.startsWith("icon.") && ICON_EXTENSIONS.includes(name.slice(5));
+    });
+    for (const ext of ICON_EXTENSIONS) {
+        const found = iconEntries.find((e) => e.name.toLowerCase() === `icon.${ext}`);
+        if (found) {
+            (0, fs_utils_1.copyFileStrict)(path.join(pluginDir, found.name), path.join(bundleDir, found.name));
+            return;
         }
-        (0, fs_utils_1.copyFileStrict)(sourcePath, path.join(bundleDir, fileName));
-        return;
     }
 }
 function uniqueStagingDir(outDir) {
@@ -235,17 +180,22 @@ async function writeTarGz(outPath, baseDir, folderName) {
     }, [folderName]);
 }
 async function bundlePlugin(parsedArgs) {
-    const { pluginDir, outDir, verbose, noNpmDeps } = parsedArgs;
+    const { pluginDir, outDir, verbose, noNpmDeps, noBuild } = parsedArgs;
     if (verbose) {
         process.stderr.write(`Bundling plugin from: ${pluginDir}\n`);
     }
-    const { pluginId, moduleExec, manifestPath } = readManifest(pluginDir);
+    const { pluginId, moduleExec, entry, manifestPath } = noBuild
+        ? (0, build_1.readManifest)(pluginDir)
+        : (0, build_1.buildPluginAssets)({ pluginDir, verbose });
     const themesPath = path.join(pluginDir, "themes");
     const hasThemes = fs.existsSync(themesPath) && fs.lstatSync(themesPath).isDirectory();
-    if (!moduleExec && !hasThemes) {
-        throw new Error("manifest has no module.exec or themes/");
+    if (entry) {
+        validateManifestEntry(pluginDir, entry);
     }
-    validateDeclaredModuleExec(pluginDir, moduleExec);
+    if (!moduleExec && !hasThemes && !entry) {
+        throw new Error("manifest has no module.exec, entry, or themes/");
+    }
+    (0, build_1.validateDeclaredModuleExec)(pluginDir, moduleExec);
     (0, fs_utils_1.ensureDirectory)(outDir);
     const stagingRoot = uniqueStagingDir(outDir);
     const bundleDir = path.join(stagingRoot, pluginId);
@@ -253,6 +203,9 @@ async function bundlePlugin(parsedArgs) {
     try {
         (0, fs_utils_1.copyFileStrict)(manifestPath, path.join(bundleDir, "openvcs.plugin.json"));
         copyIcon(pluginDir, bundleDir);
+        if (entry) {
+            copyEntryDirectory(pluginDir, bundleDir, entry);
+        }
         const sourceBinDir = path.join(pluginDir, "bin");
         if (fs.existsSync(sourceBinDir) && fs.lstatSync(sourceBinDir).isDirectory()) {
             (0, fs_utils_1.copyDirectoryRecursiveStrict)(sourceBinDir, path.join(bundleDir, "bin"));
@@ -260,8 +213,8 @@ async function bundlePlugin(parsedArgs) {
         if (hasThemes) {
             (0, fs_utils_1.copyDirectoryRecursiveStrict)(themesPath, path.join(bundleDir, "themes"));
         }
-        if (!noNpmDeps && hasPackageJson(pluginDir)) {
-            ensurePackageLock(pluginDir, verbose);
+        if (!noNpmDeps && (0, build_1.hasPackageJson)(pluginDir)) {
+            ensurePackageLock(pluginDir, bundleDir, verbose);
             installNpmDependencies(pluginDir, bundleDir, verbose);
         }
         const outPath = path.join(outDir, `${pluginId}.ovcsp`);
@@ -278,9 +231,10 @@ async function bundlePlugin(parsedArgs) {
 exports.__private = {
     ICON_EXTENSIONS,
     copyIcon,
-    readManifest,
+    readManifest: build_1.readManifest,
     rejectNativeAddonsRecursive,
     uniqueStagingDir,
-    validateDeclaredModuleExec,
+    validateDeclaredModuleExec: build_1.validateDeclaredModuleExec,
+    validateManifestEntry,
     writeTarGz,
 };

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

@@ -192,12 +192,15 @@ function writeModuleTemplate(answers) {
         private: true,
         type: "module",
         scripts: {
-            "build:ts": "tsc -p tsconfig.json",
-            build: "npm run build:ts && openvcs dist --plugin-dir . --out dist",
-            test: "openvcs dist --plugin-dir . --out dist --no-npm-deps",
+            "build:plugin": "tsc -p tsconfig.json",
+            build: "openvcs build",
+            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",
         },
@@ -215,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 { 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");
 }
 function writeThemeTemplate(answers) {
     writeCommonFiles(answers);
@@ -224,10 +227,11 @@ function writeThemeTemplate(answers) {
         version: answers.pluginVersion,
         private: true,
         scripts: {
-            build: "openvcs dist --plugin-dir . --out dist",
-            test: "openvcs dist --plugin-dir . --out dist --no-npm-deps",
+            build: "openvcs build",
+            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}`,
         },
     });
@@ -304,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/host.d.ts

@@ -0,0 +1,10 @@
+import type { PluginHost } from '../types';
+/** Describes the low-level notification sender used by `createHost`. */
+export type HostNotificationSender = (method: string, params: unknown) => void;
+/** Describes the options accepted by `createHost`. */
+export interface CreateHostOptions {
+    /** Stores the `host.log` target name to emit for diagnostic messages. */
+    logTarget?: string;
+}
+/** Creates the host notification helper used inside runtime delegates. */
+export declare function createHost(sendNotification: HostNotificationSender, options?: CreateHostOptions): PluginHost;

package/lib/runtime/host.js

@@ -0,0 +1,48 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHost = createHost;
+/** Creates the host notification helper used inside runtime delegates. */
+function createHost(sendNotification, options = {}) {
+    const logTarget = options.logTarget ?? 'openvcs.plugin';
+    return {
+        log(level, message) {
+            sendNotification('host.log', {
+                level,
+                target: logTarget,
+                message,
+            });
+        },
+        info(message) {
+            sendNotification('host.log', {
+                level: 'info',
+                target: logTarget,
+                message,
+            });
+        },
+        error(message) {
+            sendNotification('host.log', {
+                level: 'error',
+                target: logTarget,
+                message,
+            });
+        },
+        uiNotify(params) {
+            sendNotification('host.ui_notify', params);
+        },
+        statusSet(params) {
+            sendNotification('host.status_set', params);
+        },
+        emitEvent(params) {
+            sendNotification('host.event_emit', params);
+        },
+        emitVcsEvent(sessionId, requestId, event) {
+            sendNotification('vcs.event', {
+                session_id: sessionId,
+                request_id: requestId,
+                event,
+            });
+        },
+    };
+}

package/lib/runtime/index.d.ts

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