@openvcs/sdk 0.2.2 → 0.2.4

package/lib/runtime/index.js

@@ -0,0 +1,166 @@
+"use strict";
+// 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.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 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;
+}
+/** 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/transport.d.ts

@@ -0,0 +1,14 @@
+import type { JsonRpcRequest } from '../types';
+/** Describes the parsed result of draining one buffered transport chunk. */
+export interface FramedMessageParseResult {
+    /** Stores the decoded requests found in the current buffer. */
+    messages: JsonRpcRequest[];
+    /** Stores any remaining incomplete bytes. */
+    remainder: Buffer;
+}
+/** Serializes one JSON-RPC payload into an LSP-style framed stdio message. */
+export declare function serializeFramedMessage(value: unknown): Buffer;
+/** Writes one JSON-RPC payload to the supplied stdout-like stream. */
+export declare function writeFramedMessage(writer: NodeJS.WritableStream, value: unknown): Promise<void>;
+/** Parses all complete framed JSON-RPC requests currently present in a buffer. */
+export declare function parseFramedMessages(buffer: Buffer): FramedMessageParseResult;

package/lib/runtime/transport.js

@@ -0,0 +1,72 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeFramedMessage = serializeFramedMessage;
+exports.writeFramedMessage = writeFramedMessage;
+exports.parseFramedMessages = parseFramedMessages;
+/** Serializes one JSON-RPC payload into an LSP-style framed stdio message. */
+function serializeFramedMessage(value) {
+    const payload = Buffer.from(JSON.stringify(value), 'utf8');
+    const header = Buffer.from(`Content-Length: ${payload.length}\r\n\r\n`, 'utf8');
+    return Buffer.concat([header, payload]);
+}
+/** Writes one JSON-RPC payload to the supplied stdout-like stream. */
+async function writeFramedMessage(writer, value) {
+    try {
+        const serialized = serializeFramedMessage(value);
+        const canContinue = writer.write(serialized);
+        if (!canContinue) {
+            await new Promise((resolve) => writer.once('drain', resolve));
+        }
+    }
+    catch (error) {
+        console.error(`[transport] failed to write framed message: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Parses all complete framed JSON-RPC requests currently present in a buffer. */
+function parseFramedMessages(buffer) {
+    const messages = [];
+    let remainder = buffer;
+    while (true) {
+        const marker = remainder.indexOf('\r\n\r\n');
+        if (marker < 0) {
+            return { messages, remainder };
+        }
+        const header = remainder.subarray(0, marker).toString('utf8');
+        const contentLength = readContentLength(header);
+        if (contentLength == null) {
+            remainder = remainder.subarray(marker + 4);
+            continue;
+        }
+        const totalLength = marker + 4 + contentLength;
+        if (remainder.length < totalLength) {
+            return { messages, remainder };
+        }
+        const payload = remainder.subarray(marker + 4, totalLength).toString('utf8');
+        remainder = remainder.subarray(totalLength);
+        try {
+            messages.push(JSON.parse(payload));
+        }
+        catch {
+            continue;
+        }
+    }
+}
+/** Reads one `Content-Length` header value from a framed message header block. */
+function readContentLength(header) {
+    const headerLines = header.split(/\r?\n/g);
+    for (const line of headerLines) {
+        const separatorIndex = line.indexOf(':');
+        if (separatorIndex < 0) {
+            continue;
+        }
+        const name = line.slice(0, separatorIndex).trim().toLowerCase();
+        if (name !== 'content-length') {
+            continue;
+        }
+        const rawValue = Number(line.slice(separatorIndex + 1).trim());
+        return Number.isFinite(rawValue) && rawValue >= 0 ? rawValue : null;
+    }
+    return null;
+}

package/lib/types/host.d.ts

@@ -0,0 +1,57 @@
+import type { JsonRpcId } from './protocol';
+/** Enumerates the log levels accepted by the host log notification. */
+export type HostLogLevel = 'error' | 'info';
+/** Describes one `host.log` notification payload. */
+export interface HostLogParams {
+    /** Stores the emitted log severity. */
+    level: HostLogLevel;
+    /** Stores the plugin log target name. */
+    target: string;
+    /** Stores the log message text. */
+    message: string;
+}
+/** Describes one `host.ui_notify` notification payload. */
+export interface HostUiNotifyParams {
+    /** Stores the message shown by the host UI. */
+    message: string;
+    /** Stores an optional severity or category understood by the host. */
+    level?: string;
+}
+/** Describes one `host.status_set` notification payload. */
+export interface HostStatusSetParams {
+    /** Stores the status text shown by the host. */
+    text: string;
+}
+/** Describes one `host.event_emit` notification payload. */
+export interface HostEventEmitParams {
+    /** Stores the plugin-defined event name. */
+    name: string;
+    /** Stores the event payload forwarded to the host. */
+    payload?: Record<string, unknown>;
+}
+/** Describes one `vcs.event` notification payload. */
+export interface VcsEventParams {
+    /** Stores the repository session id associated with the event. */
+    session_id: string;
+    /** Stores the originating request id when one exists. */
+    request_id: JsonRpcId | null;
+    /** Stores the event payload. */
+    event: Record<string, unknown>;
+}
+/** Describes the host helper API available inside delegate handlers. */
+export interface PluginHost {
+    /** Emits a `host.log` notification. */
+    log(level: HostLogLevel, message: string): void;
+    /** Emits an informational `host.log` notification. */
+    info(message: string): void;
+    /** Emits an error `host.log` notification. */
+    error(message: string): void;
+    /** Emits a `host.ui_notify` notification. */
+    uiNotify(params: HostUiNotifyParams): void;
+    /** Emits a `host.status_set` notification. */
+    statusSet(params: HostStatusSetParams): void;
+    /** Emits a `host.event_emit` notification. */
+    emitEvent(params: HostEventEmitParams): void;
+    /** Emits a `vcs.event` notification. */
+    emitVcsEvent(sessionId: string, requestId: JsonRpcId | null, event: Record<string, unknown>): void;
+}

package/lib/types/host.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/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './host';
+export * from './plugin';
+export * from './protocol';
+export * from './vcs';

package/lib/types/index.js

@@ -0,0 +1,22 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./host"), exports);
+__exportStar(require("./plugin"), exports);
+__exportStar(require("./protocol"), exports);
+__exportStar(require("./vcs"), exports);

package/lib/types/plugin.d.ts

@@ -0,0 +1,56 @@
+import type { RequestParams, RpcMethodHandler } from './protocol';
+/** Describes the capability flags reported during plugin initialization. */
+export interface PluginImplements {
+    /** Indicates whether the plugin responds to `plugin.*` methods. */
+    plugin: boolean;
+    /** Indicates whether the plugin responds to `vcs.*` methods. */
+    vcs: boolean;
+}
+/** Describes the handshake payload returned from `plugin.initialize`. */
+export interface PluginInitializeResult {
+    /** Stores the SDK protocol version mirrored from the host. */
+    protocol_version: number;
+    /** Stores the feature groups implemented by the plugin. */
+    implements: PluginImplements;
+}
+/** Describes one optional override returned by a custom initialize handler. */
+export type PluginInitializeOverride = Partial<PluginInitializeResult>;
+/** Describes one plugin-contributed menu definition. */
+export type PluginMenuDefinition = Record<string, unknown>;
+/** Describes one plugin settings value payload. */
+export type PluginSettingsValue = Record<string, unknown>;
+/** Describes the params shape for plugin action handling. */
+export interface PluginHandleActionParams extends RequestParams {
+    /** Stores the action id selected by the user. */
+    action_id?: string;
+}
+/** Describes the params shape for plugin settings callbacks. */
+export interface PluginSettingsValuesParams extends RequestParams {
+    /** Stores the list of values supplied by the host. */
+    values?: unknown[];
+}
+/** Enumerates all host `plugin.*` method names. */
+export type PluginMethodName = 'plugin.initialize' | 'plugin.init' | 'plugin.deinit' | 'plugin.get_menus' | 'plugin.handle_action' | 'plugin.settings.defaults' | 'plugin.settings.on_load' | 'plugin.settings.on_apply' | 'plugin.settings.on_save' | 'plugin.settings.on_reset';
+/** Describes the delegate map supported by the SDK runtime for `plugin.*`. */
+export interface PluginDelegates<TContext = unknown> {
+    /** Overrides the default handshake payload returned by `plugin.initialize`. */
+    'plugin.initialize'?: RpcMethodHandler<RequestParams, PluginInitializeOverride, TContext>;
+    /** Handles plugin startup work. */
+    'plugin.init'?: RpcMethodHandler<RequestParams, null, TContext>;
+    /** Handles plugin shutdown work. */
+    'plugin.deinit'?: RpcMethodHandler<RequestParams, null, TContext>;
+    /** Returns plugin-contributed menus. */
+    'plugin.get_menus'?: RpcMethodHandler<RequestParams, PluginMenuDefinition[], TContext>;
+    /** Handles a contributed plugin action. */
+    'plugin.handle_action'?: RpcMethodHandler<PluginHandleActionParams, null, TContext>;
+    /** Returns the default settings values for the plugin. */
+    'plugin.settings.defaults'?: RpcMethodHandler<RequestParams, PluginSettingsValue[], TContext>;
+    /** Transforms settings values when they are loaded. */
+    'plugin.settings.on_load'?: RpcMethodHandler<PluginSettingsValuesParams, unknown[], TContext>;
+    /** Applies settings values to the running plugin. */
+    'plugin.settings.on_apply'?: RpcMethodHandler<PluginSettingsValuesParams, null, TContext>;
+    /** Transforms settings values before they are saved. */
+    'plugin.settings.on_save'?: RpcMethodHandler<PluginSettingsValuesParams, unknown[], TContext>;
+    /** Resets plugin settings state. */
+    'plugin.settings.on_reset'?: RpcMethodHandler<PluginSettingsValuesParams, null, TContext>;
+}

package/lib/types/plugin.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/types/protocol.d.ts

@@ -0,0 +1,77 @@
+/** Stores the protocol version mirrored from the backend host contract. */
+export declare const PROTOCOL_VERSION = 1;
+/** Stores the reserved JSON-RPC error code used for plugin failures. */
+export declare const PLUGIN_FAILURE_CODE = -32001;
+/** Stores the reserved JSON-RPC error code used for uncaught plugin errors. */
+export declare const PLUGIN_INTERNAL_ERROR_CODE = -32002;
+/** Stores the reserved JSON-RPC error code used for protocol version mismatches. */
+export declare const PROTOCOL_VERSION_MISMATCH_CODE = -32003;
+/** Represents a JSON-RPC request identifier. */
+export type JsonRpcId = number | string;
+/** Represents an untyped JSON-RPC parameter object. */
+export type RequestParams = Record<string, unknown>;
+/** Describes one JSON-RPC error payload. */
+export interface JsonRpcError {
+    /** Stores the machine-readable error code. */
+    code: number;
+    /** Stores the human-readable error message. */
+    message: string;
+    /** Stores optional structured error details. */
+    data?: unknown;
+}
+/** Describes one JSON-RPC request received from the host. */
+export interface JsonRpcRequest {
+    /** Stores the JSON-RPC protocol marker when present. */
+    jsonrpc?: string;
+    /** Stores the request identifier used to match responses. */
+    id?: JsonRpcId;
+    /** Stores the requested method name. */
+    method?: unknown;
+    /** Stores the untyped parameter payload. */
+    params?: unknown;
+}
+/** Describes one JSON-RPC notification emitted without an id. */
+export interface JsonRpcNotification {
+    /** Stores the JSON-RPC protocol marker. */
+    jsonrpc: '2.0';
+    /** Stores the notification method name. */
+    method: string;
+    /** Stores the notification payload. */
+    params?: unknown;
+}
+/** Describes one JSON-RPC success response. */
+export interface JsonRpcSuccessResponse<TResult = unknown> {
+    /** Stores the JSON-RPC protocol marker. */
+    jsonrpc: '2.0';
+    /** Stores the request identifier being answered. */
+    id: JsonRpcId;
+    /** Stores the successful result payload. */
+    result: TResult;
+}
+/** Describes one JSON-RPC error response. */
+export interface JsonRpcErrorResponse {
+    /** Stores the JSON-RPC protocol marker. */
+    jsonrpc: '2.0';
+    /** Stores the request identifier being answered. */
+    id: JsonRpcId;
+    /** Stores the structured error payload. */
+    error: JsonRpcError;
+}
+/** Describes one plugin-specific failure payload surfaced to the host. */
+export interface PluginFailure {
+    /** Stores the reserved JSON-RPC error code for plugin failures. */
+    code: typeof PLUGIN_FAILURE_CODE;
+    /** Stores the top-level failure message. */
+    message: string;
+    /** Stores nested plugin-specific failure details. */
+    data: PluginFailureData;
+}
+/** Describes the structured data embedded in a plugin failure. */
+export interface PluginFailureData {
+    /** Stores the stable plugin-specific error code. */
+    code: string;
+    /** Stores the user-facing failure message. */
+    message: string;
+}
+/** Describes one method handler used by the SDK delegate runtime. */
+export type RpcMethodHandler<TParams extends RequestParams = RequestParams, TResult = unknown, TContext = unknown> = (params: TParams, context: TContext) => TResult | Promise<TResult>;

package/lib/types/protocol.js

@@ -0,0 +1,13 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION_MISMATCH_CODE = exports.PLUGIN_INTERNAL_ERROR_CODE = exports.PLUGIN_FAILURE_CODE = exports.PROTOCOL_VERSION = void 0;
+/** Stores the protocol version mirrored from the backend host contract. */
+exports.PROTOCOL_VERSION = 1;
+/** Stores the reserved JSON-RPC error code used for plugin failures. */
+exports.PLUGIN_FAILURE_CODE = -32001;
+/** Stores the reserved JSON-RPC error code used for uncaught plugin errors. */
+exports.PLUGIN_INTERNAL_ERROR_CODE = -32002;
+/** Stores the reserved JSON-RPC error code used for protocol version mismatches. */
+exports.PROTOCOL_VERSION_MISMATCH_CODE = -32003;