@openvcs/sdk 0.2.2 → 0.2.4

package/src/lib/runtime/dispatcher.ts

@@ -0,0 +1,185 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import {
+  PLUGIN_INTERNAL_ERROR_CODE,
+  PROTOCOL_VERSION,
+  PROTOCOL_VERSION_MISMATCH_CODE,
+} from '../types';
+import type {
+  JsonRpcId,
+  PluginDelegates,
+  PluginImplements,
+  RequestParams,
+  RpcMethodHandler,
+  VcsDelegates,
+} from '../types';
+import type { PluginHost } from '../types';
+
+import type { CreatePluginRuntimeOptions, PluginRuntimeContext } from './contracts';
+import { isPluginFailure, pluginError } from './errors';
+
+/** 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 function createDefaultPluginDelegates<
+  TContext,
+>(): Required<Omit<PluginDelegates<TContext>, 'plugin.initialize'>> {
+  return {
+    async 'plugin.init'(): Promise<null> {
+      return null;
+    },
+    async 'plugin.deinit'(): Promise<null> {
+      return null;
+    },
+    async 'plugin.get_menus'(): Promise<[]> {
+      return [];
+    },
+    async 'plugin.handle_action'(): Promise<null> {
+      return null;
+    },
+    async 'plugin.settings.defaults'(): Promise<[]> {
+      return [];
+    },
+    async 'plugin.settings.on_load'(params: { values?: unknown[] }): Promise<unknown[]> {
+      return Array.isArray(params.values) ? params.values : [];
+    },
+    async 'plugin.settings.on_apply'(): Promise<null> {
+      return null;
+    },
+    async 'plugin.settings.on_save'(params: { values?: unknown[] }): Promise<unknown[]> {
+      return Array.isArray(params.values) ? params.values : [];
+    },
+    async 'plugin.settings.on_reset'(): Promise<null> {
+      return null;
+    },
+  };
+}
+
+/** Creates the JSON-RPC dispatcher used by the SDK plugin runtime. */
+export function createRuntimeDispatcher(
+  options: CreatePluginRuntimeOptions,
+  host: PluginHost,
+  writer: DispatcherResponseWriter,
+): RuntimeRequestDispatcher {
+  const defaultPluginDelegates = createDefaultPluginDelegates<PluginRuntimeContext>();
+  const pluginDelegates = options.plugin ?? {};
+  const vcsDelegates = options.vcs ?? {};
+  const runtimeImplements = buildRuntimeImplements(options.implements, options.vcs);
+  const timeout = options.timeout;
+  const typedPluginDelegates = pluginDelegates as Record<
+    string,
+    RpcMethodHandler<RequestParams, unknown, PluginRuntimeContext> | undefined
+  >;
+  const typedDefaultPluginDelegates = defaultPluginDelegates as Record<
+    string,
+    RpcMethodHandler<RequestParams, unknown, PluginRuntimeContext> | undefined
+  >;
+  const typedVcsDelegates = vcsDelegates as Record<
+    string,
+    RpcMethodHandler<RequestParams, unknown, PluginRuntimeContext> | undefined
+  >;
+
+  return async (id: JsonRpcId, method: string, params: RequestParams): Promise<void> => {
+    try {
+      if (method === 'plugin.initialize') {
+        const expectedVersion = params.expected_protocol_version;
+        if (typeof expectedVersion === 'number' && expectedVersion !== PROTOCOL_VERSION) {
+          writer.sendError(id, PROTOCOL_VERSION_MISMATCH_CODE, 'protocol version mismatch', {
+            code: 'protocol-version-mismatch',
+            message: `host expects protocol ${expectedVersion}, plugin supports ${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 ?? PROTOCOL_VERSION,
+          implements: {
+            ...runtimeImplements,
+            ...override.implements,
+          },
+        });
+        return;
+      }
+
+      const handler =
+        typedPluginDelegates[method] ??
+        typedDefaultPluginDelegates[method] ??
+        typedVcsDelegates[method];
+
+      if (!handler) {
+        throw pluginError('rpc-method-not-found', `method '${method}' is not implemented`);
+      }
+
+      let result: unknown;
+      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 as Error).name === 'AbortError') {
+            throw 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 (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, PLUGIN_INTERNAL_ERROR_CODE, messageText, {
+        code: 'plugin-internal-error',
+        message: messageText,
+      });
+    }
+  };
+}
+
+/** Builds the handshake capability flags returned from `plugin.initialize`. */
+function buildRuntimeImplements(
+  overrides: Partial<PluginImplements> | undefined,
+  vcsDelegates: VcsDelegates<PluginRuntimeContext> | undefined,
+): PluginImplements {
+  return {
+    plugin: overrides?.plugin ?? true,
+    vcs: overrides?.vcs ?? Boolean(vcsDelegates && Object.keys(vcsDelegates).length > 0),
+  };
+}

package/src/lib/runtime/errors.ts

@@ -0,0 +1,27 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PLUGIN_FAILURE_CODE } from '../types';
+import type { PluginFailure } from '../types';
+
+/** Builds the host-facing plugin failure payload used for operational errors. */
+export function pluginError(code: string, message: string): PluginFailure {
+  return {
+    code: PLUGIN_FAILURE_CODE,
+    message,
+    data: {
+      code,
+      message,
+    },
+  };
+}
+
+/** Returns whether the supplied value is a structured plugin failure. */
+export function isPluginFailure(value: unknown): value is PluginFailure {
+  if (value == null || typeof value !== 'object') {
+    return false;
+  }
+
+  const candidate = value as Partial<PluginFailure>;
+  return candidate.code === PLUGIN_FAILURE_CODE && typeof candidate.message === 'string';
+}

package/src/lib/runtime/host.ts

@@ -0,0 +1,72 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  HostEventEmitParams,
+  HostLogLevel,
+  HostStatusSetParams,
+  HostUiNotifyParams,
+  JsonRpcId,
+  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 function createHost(
+  sendNotification: HostNotificationSender,
+  options: CreateHostOptions = {},
+): PluginHost {
+  const logTarget = options.logTarget ?? 'openvcs.plugin';
+
+  return {
+    log(level: HostLogLevel, message: string): void {
+      sendNotification('host.log', {
+        level,
+        target: logTarget,
+        message,
+      });
+    },
+    info(message: string): void {
+      sendNotification('host.log', {
+        level: 'info',
+        target: logTarget,
+        message,
+      });
+    },
+    error(message: string): void {
+      sendNotification('host.log', {
+        level: 'error',
+        target: logTarget,
+        message,
+      });
+    },
+    uiNotify(params: HostUiNotifyParams): void {
+      sendNotification('host.ui_notify', params);
+    },
+    statusSet(params: HostStatusSetParams): void {
+      sendNotification('host.status_set', params);
+    },
+    emitEvent(params: HostEventEmitParams): void {
+      sendNotification('host.event_emit', params);
+    },
+    emitVcsEvent(
+      sessionId: string,
+      requestId: JsonRpcId | null,
+      event: Record<string, unknown>,
+    ): void {
+      sendNotification('vcs.event', {
+        session_id: sessionId,
+        request_id: requestId,
+        event,
+      });
+    },
+  };
+}

package/src/lib/runtime/index.ts

@@ -0,0 +1,201 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type { JsonRpcId, JsonRpcRequest, RequestParams } from '../types';
+
+import type {
+  CreatePluginRuntimeOptions,
+  PluginRuntime,
+  PluginRuntimeContext,
+  PluginRuntimeTransport,
+} from './contracts';
+import { createRuntimeDispatcher } from './dispatcher';
+import { createHost } from './host';
+import { parseFramedMessages, writeFramedMessage } from './transport';
+
+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 function createPluginRuntime(
+  options: CreatePluginRuntimeOptions = {},
+): PluginRuntime {
+  let buffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+  let processing: Promise<void> = Promise.resolve();
+  let started = false;
+  let currentTransport: PluginRuntimeTransport | null = null;
+  let chunkLock: Promise<void> = Promise.resolve();
+
+  const runtime: PluginRuntime = {
+    start(transport: PluginRuntimeTransport = defaultTransport()): void {
+      if (started) {
+        return;
+      }
+
+      started = true;
+      currentTransport = transport;
+      transport.stdin.on('data', (chunk: Buffer | string) => {
+        runtime.consumeChunk(chunk);
+      });
+      transport.stdin.on('error', () => {
+        process.exit(1);
+      });
+      options.onStart?.();
+    },
+    stop(): void {
+      if (!started) {
+        return;
+      }
+      started = false;
+      processing = processing
+        .catch(async (error: unknown) => {
+          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: Buffer | string): void {
+      if (!started) {
+        return;
+      }
+
+      const lock = chunkLock.then(() => {
+        buffer = Buffer.concat([buffer, normalizeChunk(chunk)]);
+        const parsed = parseFramedMessages(buffer);
+        buffer = parsed.remainder;
+
+        for (const request of parsed.messages) {
+          processing = processing
+            .then(async () => {
+              await runtime.dispatchRequest(request);
+            })
+            .catch((error: unknown) => {
+              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: JsonRpcRequest): Promise<void> {
+      const id = request.id;
+      const host = createRuntimeHost(currentTransport, options.logTarget);
+      const method = asTrimmedString(request.method);
+      const validationErrors: string[] = [];
+      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 = createRuntimeDispatcher(options, host, {
+        async sendResult<TResult>(requestId: JsonRpcId, result: TResult): Promise<void> {
+          await sendMessage(currentTransport, {
+            jsonrpc: '2.0',
+            id: requestId,
+            result,
+          });
+        },
+        async sendError(requestId: JsonRpcId, code: number, message: string, data?: unknown): Promise<void> {
+          await sendMessage(currentTransport, {
+            jsonrpc: '2.0',
+            id: requestId,
+            error: {
+              code,
+              message,
+              ...(data == null ? {} : { data }),
+            },
+          });
+        },
+      });
+
+      const methodName = method as string;
+      const params = asRecord(request.params) ?? {};
+      const requestId = id as JsonRpcId;
+      await dispatcher(requestId, methodName, params);
+    },
+  };
+
+  return runtime;
+}
+
+/** Starts a previously created plugin runtime on process stdio. */
+export function startPluginRuntime(
+  runtime: PluginRuntime,
+  transport?: PluginRuntimeTransport,
+): void {
+  runtime.start(transport);
+}
+
+/** Returns the default stdio transport used by the runtime. */
+function defaultTransport(): PluginRuntimeTransport {
+  return {
+    stdin: process.stdin,
+    stdout: process.stdout,
+  };
+}
+
+/** Sends one JSON-RPC response or notification through the active transport. */
+async function sendMessage(
+  transport: PluginRuntimeTransport | null,
+  value: unknown,
+): Promise<void> {
+  await writeFramedMessage((transport ?? defaultTransport()).stdout, value);
+}
+
+/** Builds the host helper for the currently active transport. */
+function createRuntimeHost(
+  transport: PluginRuntimeTransport | null,
+  logTarget: string | undefined,
+) {
+  return createHost(
+    async (method: string, params: unknown) => {
+      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: unknown): value is RequestParams {
+  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: unknown): string | null {
+  return typeof value === 'string' ? value.trim() : null;
+}
+
+/** Coerces unknown params to a Record, returning null for invalid input. */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (isRequestParams(value)) {
+    return value as Record<string, unknown>;
+  }
+  return null;
+}
+
+/** Normalizes incoming data chunks to UTF-8 buffers. */
+function normalizeChunk(chunk: Buffer | string): Buffer {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+}

package/src/lib/runtime/transport.ts

@@ -0,0 +1,93 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+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 function serializeFramedMessage(value: unknown): Buffer {
+  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. */
+export async function writeFramedMessage(
+  writer: NodeJS.WritableStream,
+  value: unknown,
+): Promise<void> {
+  try {
+    const serialized = serializeFramedMessage(value);
+    const canContinue = writer.write(serialized);
+    if (!canContinue) {
+      await new Promise<void>((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. */
+export function parseFramedMessages(buffer: Buffer): FramedMessageParseResult {
+  const messages: JsonRpcRequest[] = [];
+  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) as JsonRpcRequest);
+    } catch {
+      continue;
+    }
+  }
+}
+
+/** Reads one `Content-Length` header value from a framed message header block. */
+function readContentLength(header: string): number | null {
+  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/src/lib/types/host.ts

@@ -0,0 +1,71 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+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/src/lib/types/index.ts

@@ -0,0 +1,7 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+export * from './host';
+export * from './plugin';
+export * from './protocol';
+export * from './vcs';