@openvcs/sdk 0.2.3 → 0.2.5

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';

package/src/lib/types/plugin.ts

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

@@ -0,0 +1,97 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/** Stores the protocol version mirrored from the backend host contract. */
+export const PROTOCOL_VERSION = 1;
+
+/** Stores the reserved JSON-RPC error code used for plugin failures. */
+export const PLUGIN_FAILURE_CODE = -32001;
+
+/** Stores the reserved JSON-RPC error code used for uncaught plugin errors. */
+export const PLUGIN_INTERNAL_ERROR_CODE = -32002;
+
+/** Stores the reserved JSON-RPC error code used for protocol version mismatches. */
+export 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>;