@openvcs/sdk 0.2.5 → 0.2.6

package/README.md

@@ -81,10 +81,62 @@ export const PluginDefinition: PluginModuleDefinition = {
 export function OnPluginStart(): void {}
 ```
 
+VCS backends can also derive from `VcsDelegateBase` and attach exact `vcs.*`
+delegates during startup:
+
+```ts
+import {
+  VcsDelegateBase,
+  type PluginRuntimeContext,
+  type PluginModuleDefinition,
+} from '@openvcs/sdk/runtime';
+import type { RequestParams, VcsCapabilities } from '@openvcs/sdk/types';
+
+class ExampleVcsDelegates extends VcsDelegateBase<{ cwd: string }> {
+  override getCaps(
+    _params: RequestParams,
+    _context: PluginRuntimeContext,
+  ): VcsCapabilities {
+    return {
+      commits: true,
+      branches: true,
+      tags: false,
+      staging: true,
+      push_pull: true,
+      fast_forward: true,
+    };
+  }
+}
+
+export const PluginDefinition: PluginModuleDefinition = {};
+
+export function OnPluginStart(): void {
+  const vcs = new ExampleVcsDelegates({ cwd: process.cwd() });
+  PluginDefinition.vcs = vcs.toDelegates();
+}
+```
+
+Define ordinary prototype methods such as `getCaps()` and `commitIndex()` on the
+subclass. `toDelegates()` maps those camelCase methods to the exact host method
+names like `vcs.get_caps` and `vcs.commit_index`, and only registers methods
+that differ from the SDK base class. Use `override` with the full params/context
+signature so TypeScript checks your subclass against the SDK contract. Base
+stubs throw through an internal `never`-returning helper, which is why concrete
+plugins should always implement the methods they intend to expose.
+
+### Compile-time override safety
+
+The SDK enforces correct method signatures at compile time.  Subclasses that
+override with the wrong return type or parameter shape produce a TypeScript error.
+The SDK test suite includes `test/vcs-delegate-base.types.ts` which explicitly
+verifies that incompatible overrides (e.g. returning `string` instead of
+`VcsCapabilities`) fail the compiler under `@ts-expect-error`.  Runtime tests
+in `test/vcs-delegate-base.test.js` cover behavior — not signatures.
+
 Runtime and protocol imports are exposed as npm subpaths:
 
 ```ts
-import { pluginError } from '@openvcs/sdk/runtime';
+import { VcsDelegateBase, pluginError } from '@openvcs/sdk/runtime';
 import type { PluginDelegates, VcsDelegates } from '@openvcs/sdk/types';
 ```
 

package/lib/runtime/index.d.ts

@@ -6,5 +6,7 @@ export { isPluginFailure, pluginError } from './errors';
 export { createPluginRuntime } from './factory';
 export { createHost } from './host';
 export { bootstrapPluginModule, createRegisteredPluginRuntime, } from './registration';
+export { VcsDelegateBase } from './vcs-delegate-base';
+export type { VcsDelegateAssignments } from './vcs-delegate-metadata';
 /** Starts a previously created plugin runtime on process stdio. */
 export declare function startPluginRuntime(runtime: PluginRuntime, transport?: PluginRuntimeTransport): void;

package/lib/runtime/index.js

@@ -2,7 +2,7 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
+exports.VcsDelegateBase = exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
 exports.startPluginRuntime = startPluginRuntime;
 var dispatcher_1 = require("./dispatcher");
 Object.defineProperty(exports, "createDefaultPluginDelegates", { enumerable: true, get: function () { return dispatcher_1.createDefaultPluginDelegates; } });
@@ -17,6 +17,8 @@ Object.defineProperty(exports, "createHost", { enumerable: true, get: function (
 var registration_1 = require("./registration");
 Object.defineProperty(exports, "bootstrapPluginModule", { enumerable: true, get: function () { return registration_1.bootstrapPluginModule; } });
 Object.defineProperty(exports, "createRegisteredPluginRuntime", { enumerable: true, get: function () { return registration_1.createRegisteredPluginRuntime; } });
+var vcs_delegate_base_1 = require("./vcs-delegate-base");
+Object.defineProperty(exports, "VcsDelegateBase", { enumerable: true, get: function () { return vcs_delegate_base_1.VcsDelegateBase; } });
 /** Starts a previously created plugin runtime on process stdio. */
 function startPluginRuntime(runtime, transport) {
     runtime.start(transport);

package/lib/runtime/vcs-delegate-base.d.ts

@@ -0,0 +1,125 @@
+import type * as VcsTypes from '../types';
+import type { PluginRuntimeContext } from './contracts';
+import { type VcsDelegateAssignments, type VcsDelegateMethodName } from './vcs-delegate-metadata';
+/** Describes one synchronous or asynchronous VCS delegate return value. */
+type VcsHandlerResult<TResult> = TResult | Promise<TResult>;
+/** Builds exact `vcs.*` delegates from ordinary class methods. */
+export declare abstract class VcsDelegateBase<TDeps, TContext = PluginRuntimeContext> {
+    /** Stores the runtime services exposed to the delegate implementation. */
+    protected readonly deps: TDeps;
+    /** Creates one delegate base with the provided runtime dependencies. */
+    constructor(deps: TDeps);
+    /** Builds an SDK `vcs.*` delegate map from the subclass overrides. */
+    toDelegates(): VcsDelegateAssignments<TContext>;
+    /** Assigns one typed class method to its exact `vcs.*` delegate name. */
+    private assignDelegate;
+    /**
+     * Throws when a subclass does not implement one required delegate method.
+     *
+     * The `never` return type is intentional: base stubs should never contribute
+     * a usable value, and subclasses should override the method with the exact
+     * signature inherited from `VcsDelegateBase`.
+     */
+    protected unimplemented(methodName: VcsDelegateMethodName): never;
+    /** Handles `vcs.get_caps`. */
+    getCaps(_params: VcsTypes.RequestParams, _context: TContext): VcsHandlerResult<VcsTypes.VcsCapabilities>;
+    /** Handles `vcs.open`. */
+    open(_params: VcsTypes.VcsOpenParams, _context: TContext): VcsHandlerResult<VcsTypes.VcsSessionResult>;
+    /** Handles `vcs.close`. */
+    close(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.clone_repo`. */
+    cloneRepo(_params: VcsTypes.VcsCloneRepoParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.get_workdir`. */
+    getWorkdir(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<string>;
+    /** Handles `vcs.get_current_branch`. */
+    getCurrentBranch(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<string | null>;
+    /** Handles `vcs.list_branches`. */
+    listBranches(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<VcsTypes.VcsBranchEntry[]>;
+    /** Handles `vcs.list_local_branches`. */
+    listLocalBranches(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<string[]>;
+    /** Handles `vcs.create_branch`. */
+    createBranch(_params: VcsTypes.VcsCreateBranchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.checkout_branch`. */
+    checkoutBranch(_params: VcsTypes.VcsCheckoutBranchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.ensure_remote`. */
+    ensureRemote(_params: VcsTypes.VcsEnsureRemoteParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.list_remotes`. */
+    listRemotes(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<VcsTypes.VcsRemoteEntry[]>;
+    /** Handles `vcs.remove_remote`. */
+    removeRemote(_params: VcsTypes.VcsRemoveRemoteParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.fetch`. */
+    fetch(_params: VcsTypes.VcsFetchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.fetch_with_options`. */
+    fetchWithOptions(_params: VcsTypes.VcsFetchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.push`. */
+    push(_params: VcsTypes.VcsPushParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.pull_ff_only`. */
+    pullFfOnly(_params: VcsTypes.VcsPullFfOnlyParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.commit`. */
+    commit(_params: VcsTypes.VcsCommitParams, _context: TContext): VcsHandlerResult<string>;
+    /** Handles `vcs.commit_index`. */
+    commitIndex(_params: VcsTypes.VcsCommitParams, _context: TContext): VcsHandlerResult<string>;
+    /** Handles `vcs.get_status_summary`. */
+    getStatusSummary(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<VcsTypes.StatusSummary>;
+    /** Handles `vcs.get_status_payload`. */
+    getStatusPayload(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<VcsTypes.StatusPayload>;
+    /** Handles `vcs.list_commits`. */
+    listCommits(_params: VcsTypes.VcsListCommitsParams, _context: TContext): VcsHandlerResult<VcsTypes.CommitEntry[]>;
+    /** Handles `vcs.diff_file`. */
+    diffFile(_params: VcsTypes.VcsDiffFileParams, _context: TContext): VcsHandlerResult<string[]>;
+    /** Handles `vcs.diff_commit`. */
+    diffCommit(_params: VcsTypes.VcsDiffCommitParams, _context: TContext): VcsHandlerResult<string[]>;
+    /** Handles `vcs.get_conflict_details`. */
+    getConflictDetails(_params: VcsTypes.VcsGetConflictDetailsParams, _context: TContext): VcsHandlerResult<VcsTypes.VcsConflictDetails>;
+    /** Handles `vcs.checkout_conflict_side`. */
+    checkoutConflictSide(_params: VcsTypes.VcsCheckoutConflictSideParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.write_merge_result`. */
+    writeMergeResult(_params: VcsTypes.VcsWriteMergeResultParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.stage_patch`. */
+    stagePatch(_params: VcsTypes.VcsStagePatchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.discard_paths`. */
+    discardPaths(_params: VcsTypes.VcsDiscardPathsParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.apply_reverse_patch`. */
+    applyReversePatch(_params: VcsTypes.VcsApplyReversePatchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.delete_branch`. */
+    deleteBranch(_params: VcsTypes.VcsDeleteBranchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.rename_branch`. */
+    renameBranch(_params: VcsTypes.VcsRenameBranchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.merge_into_current`. */
+    mergeIntoCurrent(_params: VcsTypes.VcsMergeIntoCurrentParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.merge_abort`. */
+    mergeAbort(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.merge_continue`. */
+    mergeContinue(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.is_merge_in_progress`. */
+    isMergeInProgress(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<boolean>;
+    /** Handles `vcs.set_branch_upstream`. */
+    setBranchUpstream(_params: VcsTypes.VcsSetBranchUpstreamParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.get_branch_upstream`. */
+    getBranchUpstream(_params: VcsTypes.VcsGetBranchUpstreamParams, _context: TContext): VcsHandlerResult<string | null>;
+    /** Handles `vcs.hard_reset_head`. */
+    hardResetHead(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.reset_soft_to`. */
+    resetSoftTo(_params: VcsTypes.VcsResetSoftToParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.get_identity`. */
+    getIdentity(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<VcsTypes.VcsIdentity | null>;
+    /** Handles `vcs.set_identity_local`. */
+    setIdentityLocal(_params: VcsTypes.VcsSetIdentityLocalParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.list_stashes`. */
+    listStashes(_params: VcsTypes.VcsSessionParams, _context: TContext): VcsHandlerResult<VcsTypes.StashEntry[]>;
+    /** Handles `vcs.stash_push`. */
+    stashPush(_params: VcsTypes.VcsStashPushParams, _context: TContext): VcsHandlerResult<string>;
+    /** Handles `vcs.stash_apply`. */
+    stashApply(_params: VcsTypes.VcsStashSelectorParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.stash_pop`. */
+    stashPop(_params: VcsTypes.VcsStashSelectorParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.stash_drop`. */
+    stashDrop(_params: VcsTypes.VcsStashSelectorParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.stash_show`. */
+    stashShow(_params: VcsTypes.VcsStashSelectorParams, _context: TContext): VcsHandlerResult<string>;
+    /** Handles `vcs.cherry_pick`. */
+    cherryPick(_params: VcsTypes.VcsCherryPickParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.revert_commit`. */
+    revertCommit(_params: VcsTypes.VcsRevertCommitParams, _context: TContext): VcsHandlerResult<null>;
+}
+export {};

package/lib/runtime/vcs-delegate-base.js

@@ -0,0 +1,249 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VcsDelegateBase = void 0;
+const vcs_delegate_metadata_1 = require("./vcs-delegate-metadata");
+/** Builds exact `vcs.*` delegates from ordinary class methods. */
+class VcsDelegateBase {
+    /** Stores the runtime services exposed to the delegate implementation. */
+    deps;
+    /** Creates one delegate base with the provided runtime dependencies. */
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Builds an SDK `vcs.*` delegate map from the subclass overrides. */
+    toDelegates() {
+        const delegates = {};
+        const delegatePrototype = Object.getPrototypeOf(this);
+        const basePrototype = VcsDelegateBase.prototype;
+        for (const delegateMethod of Object.keys(vcs_delegate_metadata_1.VCS_DELEGATE_METHOD_MAPPINGS)) {
+            const handler = delegatePrototype?.[delegateMethod];
+            if (typeof handler !== 'function' || handler === basePrototype[delegateMethod]) {
+                continue;
+            }
+            this.assignDelegate(delegates, delegateMethod, handler);
+        }
+        return delegates;
+    }
+    /** Assigns one typed class method to its exact `vcs.*` delegate name. */
+    assignDelegate(delegates, delegateMethod, handler) {
+        const rpcMethod = vcs_delegate_metadata_1.VCS_DELEGATE_METHOD_MAPPINGS[delegateMethod];
+        // `bind` loses the method-specific key correlation here; the cast is
+        // safe because `assignDelegate` is only called with handlers that were
+        // verified against `VcsDelegateBindings<TContext>` in the loop above.
+        const boundHandler = handler.bind(this);
+        delegates[rpcMethod] = boundHandler;
+    }
+    /**
+     * Throws when a subclass does not implement one required delegate method.
+     *
+     * The `never` return type is intentional: base stubs should never contribute
+     * a usable value, and subclasses should override the method with the exact
+     * signature inherited from `VcsDelegateBase`.
+     */
+    unimplemented(methodName) {
+        throw new Error(`VCS delegate method '${methodName}' must be overridden before registration`);
+    }
+    /** Handles `vcs.get_caps`. */
+    getCaps(_params, _context) {
+        return this.unimplemented('getCaps');
+    }
+    /** Handles `vcs.open`. */
+    open(_params, _context) {
+        return this.unimplemented('open');
+    }
+    /** Handles `vcs.close`. */
+    close(_params, _context) {
+        return this.unimplemented('close');
+    }
+    /** Handles `vcs.clone_repo`. */
+    cloneRepo(_params, _context) {
+        return this.unimplemented('cloneRepo');
+    }
+    /** Handles `vcs.get_workdir`. */
+    getWorkdir(_params, _context) {
+        return this.unimplemented('getWorkdir');
+    }
+    /** Handles `vcs.get_current_branch`. */
+    getCurrentBranch(_params, _context) {
+        return this.unimplemented('getCurrentBranch');
+    }
+    /** Handles `vcs.list_branches`. */
+    listBranches(_params, _context) {
+        return this.unimplemented('listBranches');
+    }
+    /** Handles `vcs.list_local_branches`. */
+    listLocalBranches(_params, _context) {
+        return this.unimplemented('listLocalBranches');
+    }
+    /** Handles `vcs.create_branch`. */
+    createBranch(_params, _context) {
+        return this.unimplemented('createBranch');
+    }
+    /** Handles `vcs.checkout_branch`. */
+    checkoutBranch(_params, _context) {
+        return this.unimplemented('checkoutBranch');
+    }
+    /** Handles `vcs.ensure_remote`. */
+    ensureRemote(_params, _context) {
+        return this.unimplemented('ensureRemote');
+    }
+    /** Handles `vcs.list_remotes`. */
+    listRemotes(_params, _context) {
+        return this.unimplemented('listRemotes');
+    }
+    /** Handles `vcs.remove_remote`. */
+    removeRemote(_params, _context) {
+        return this.unimplemented('removeRemote');
+    }
+    /** Handles `vcs.fetch`. */
+    fetch(_params, _context) {
+        return this.unimplemented('fetch');
+    }
+    /** Handles `vcs.fetch_with_options`. */
+    fetchWithOptions(_params, _context) {
+        return this.unimplemented('fetchWithOptions');
+    }
+    /** Handles `vcs.push`. */
+    push(_params, _context) {
+        return this.unimplemented('push');
+    }
+    /** Handles `vcs.pull_ff_only`. */
+    pullFfOnly(_params, _context) {
+        return this.unimplemented('pullFfOnly');
+    }
+    /** Handles `vcs.commit`. */
+    commit(_params, _context) {
+        return this.unimplemented('commit');
+    }
+    /** Handles `vcs.commit_index`. */
+    commitIndex(_params, _context) {
+        return this.unimplemented('commitIndex');
+    }
+    /** Handles `vcs.get_status_summary`. */
+    getStatusSummary(_params, _context) {
+        return this.unimplemented('getStatusSummary');
+    }
+    /** Handles `vcs.get_status_payload`. */
+    getStatusPayload(_params, _context) {
+        return this.unimplemented('getStatusPayload');
+    }
+    /** Handles `vcs.list_commits`. */
+    listCommits(_params, _context) {
+        return this.unimplemented('listCommits');
+    }
+    /** Handles `vcs.diff_file`. */
+    diffFile(_params, _context) {
+        return this.unimplemented('diffFile');
+    }
+    /** Handles `vcs.diff_commit`. */
+    diffCommit(_params, _context) {
+        return this.unimplemented('diffCommit');
+    }
+    /** Handles `vcs.get_conflict_details`. */
+    getConflictDetails(_params, _context) {
+        return this.unimplemented('getConflictDetails');
+    }
+    /** Handles `vcs.checkout_conflict_side`. */
+    checkoutConflictSide(_params, _context) {
+        return this.unimplemented('checkoutConflictSide');
+    }
+    /** Handles `vcs.write_merge_result`. */
+    writeMergeResult(_params, _context) {
+        return this.unimplemented('writeMergeResult');
+    }
+    /** Handles `vcs.stage_patch`. */
+    stagePatch(_params, _context) {
+        return this.unimplemented('stagePatch');
+    }
+    /** Handles `vcs.discard_paths`. */
+    discardPaths(_params, _context) {
+        return this.unimplemented('discardPaths');
+    }
+    /** Handles `vcs.apply_reverse_patch`. */
+    applyReversePatch(_params, _context) {
+        return this.unimplemented('applyReversePatch');
+    }
+    /** Handles `vcs.delete_branch`. */
+    deleteBranch(_params, _context) {
+        return this.unimplemented('deleteBranch');
+    }
+    /** Handles `vcs.rename_branch`. */
+    renameBranch(_params, _context) {
+        return this.unimplemented('renameBranch');
+    }
+    /** Handles `vcs.merge_into_current`. */
+    mergeIntoCurrent(_params, _context) {
+        return this.unimplemented('mergeIntoCurrent');
+    }
+    /** Handles `vcs.merge_abort`. */
+    mergeAbort(_params, _context) {
+        return this.unimplemented('mergeAbort');
+    }
+    /** Handles `vcs.merge_continue`. */
+    mergeContinue(_params, _context) {
+        return this.unimplemented('mergeContinue');
+    }
+    /** Handles `vcs.is_merge_in_progress`. */
+    isMergeInProgress(_params, _context) {
+        return this.unimplemented('isMergeInProgress');
+    }
+    /** Handles `vcs.set_branch_upstream`. */
+    setBranchUpstream(_params, _context) {
+        return this.unimplemented('setBranchUpstream');
+    }
+    /** Handles `vcs.get_branch_upstream`. */
+    getBranchUpstream(_params, _context) {
+        return this.unimplemented('getBranchUpstream');
+    }
+    /** Handles `vcs.hard_reset_head`. */
+    hardResetHead(_params, _context) {
+        return this.unimplemented('hardResetHead');
+    }
+    /** Handles `vcs.reset_soft_to`. */
+    resetSoftTo(_params, _context) {
+        return this.unimplemented('resetSoftTo');
+    }
+    /** Handles `vcs.get_identity`. */
+    getIdentity(_params, _context) {
+        return this.unimplemented('getIdentity');
+    }
+    /** Handles `vcs.set_identity_local`. */
+    setIdentityLocal(_params, _context) {
+        return this.unimplemented('setIdentityLocal');
+    }
+    /** Handles `vcs.list_stashes`. */
+    listStashes(_params, _context) {
+        return this.unimplemented('listStashes');
+    }
+    /** Handles `vcs.stash_push`. */
+    stashPush(_params, _context) {
+        return this.unimplemented('stashPush');
+    }
+    /** Handles `vcs.stash_apply`. */
+    stashApply(_params, _context) {
+        return this.unimplemented('stashApply');
+    }
+    /** Handles `vcs.stash_pop`. */
+    stashPop(_params, _context) {
+        return this.unimplemented('stashPop');
+    }
+    /** Handles `vcs.stash_drop`. */
+    stashDrop(_params, _context) {
+        return this.unimplemented('stashDrop');
+    }
+    /** Handles `vcs.stash_show`. */
+    stashShow(_params, _context) {
+        return this.unimplemented('stashShow');
+    }
+    /** Handles `vcs.cherry_pick`. */
+    cherryPick(_params, _context) {
+        return this.unimplemented('cherryPick');
+    }
+    /** Handles `vcs.revert_commit`. */
+    revertCommit(_params, _context) {
+        return this.unimplemented('revertCommit');
+    }
+}
+exports.VcsDelegateBase = VcsDelegateBase;

package/lib/runtime/vcs-delegate-metadata.d.ts

@@ -0,0 +1,120 @@
+import type * as VcsTypes from '../types';
+import type { PluginRuntimeContext } from './contracts';
+/** Stores the typed class-method signatures supported by `VcsDelegateBase`. */
+export type VcsDelegateBindings<TContext> = {
+    getCaps: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.get_caps']>;
+    open: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.open']>;
+    close: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.close']>;
+    cloneRepo: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.clone_repo']>;
+    getWorkdir: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.get_workdir']>;
+    getCurrentBranch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.get_current_branch']>;
+    listBranches: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.list_branches']>;
+    listLocalBranches: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.list_local_branches']>;
+    createBranch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.create_branch']>;
+    checkoutBranch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.checkout_branch']>;
+    ensureRemote: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.ensure_remote']>;
+    listRemotes: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.list_remotes']>;
+    removeRemote: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.remove_remote']>;
+    fetch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.fetch']>;
+    fetchWithOptions: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.fetch_with_options']>;
+    push: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.push']>;
+    pullFfOnly: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.pull_ff_only']>;
+    commit: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.commit']>;
+    commitIndex: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.commit_index']>;
+    getStatusSummary: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.get_status_summary']>;
+    getStatusPayload: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.get_status_payload']>;
+    listCommits: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.list_commits']>;
+    diffFile: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.diff_file']>;
+    diffCommit: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.diff_commit']>;
+    getConflictDetails: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.get_conflict_details']>;
+    checkoutConflictSide: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.checkout_conflict_side']>;
+    writeMergeResult: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.write_merge_result']>;
+    stagePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_patch']>;
+    discardPaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.discard_paths']>;
+    applyReversePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.apply_reverse_patch']>;
+    deleteBranch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.delete_branch']>;
+    renameBranch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.rename_branch']>;
+    mergeIntoCurrent: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.merge_into_current']>;
+    mergeAbort: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.merge_abort']>;
+    mergeContinue: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.merge_continue']>;
+    isMergeInProgress: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.is_merge_in_progress']>;
+    setBranchUpstream: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.set_branch_upstream']>;
+    getBranchUpstream: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.get_branch_upstream']>;
+    hardResetHead: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.hard_reset_head']>;
+    resetSoftTo: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.reset_soft_to']>;
+    getIdentity: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.get_identity']>;
+    setIdentityLocal: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.set_identity_local']>;
+    listStashes: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.list_stashes']>;
+    stashPush: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stash_push']>;
+    stashApply: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stash_apply']>;
+    stashPop: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stash_pop']>;
+    stashDrop: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stash_drop']>;
+    stashShow: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stash_show']>;
+    cherryPick: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.cherry_pick']>;
+    revertCommit: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.revert_commit']>;
+};
+/** Enumerates the class-friendly method names recognized by `VcsDelegateBase`. */
+export type VcsDelegateMethodName = keyof VcsDelegateBindings<PluginRuntimeContext>;
+/** Maps one delegate class method to the SDK runtime RPC key it implements. */
+export declare const VCS_DELEGATE_METHOD_MAPPINGS: {
+    readonly getCaps: "vcs.get_caps";
+    readonly open: "vcs.open";
+    readonly close: "vcs.close";
+    readonly cloneRepo: "vcs.clone_repo";
+    readonly getWorkdir: "vcs.get_workdir";
+    readonly getCurrentBranch: "vcs.get_current_branch";
+    readonly listBranches: "vcs.list_branches";
+    readonly listLocalBranches: "vcs.list_local_branches";
+    readonly createBranch: "vcs.create_branch";
+    readonly checkoutBranch: "vcs.checkout_branch";
+    readonly ensureRemote: "vcs.ensure_remote";
+    readonly listRemotes: "vcs.list_remotes";
+    readonly removeRemote: "vcs.remove_remote";
+    readonly fetch: "vcs.fetch";
+    readonly fetchWithOptions: "vcs.fetch_with_options";
+    readonly push: "vcs.push";
+    readonly pullFfOnly: "vcs.pull_ff_only";
+    readonly commit: "vcs.commit";
+    readonly commitIndex: "vcs.commit_index";
+    readonly getStatusSummary: "vcs.get_status_summary";
+    readonly getStatusPayload: "vcs.get_status_payload";
+    readonly listCommits: "vcs.list_commits";
+    readonly diffFile: "vcs.diff_file";
+    readonly diffCommit: "vcs.diff_commit";
+    readonly getConflictDetails: "vcs.get_conflict_details";
+    readonly checkoutConflictSide: "vcs.checkout_conflict_side";
+    readonly writeMergeResult: "vcs.write_merge_result";
+    readonly stagePatch: "vcs.stage_patch";
+    readonly discardPaths: "vcs.discard_paths";
+    readonly applyReversePatch: "vcs.apply_reverse_patch";
+    readonly deleteBranch: "vcs.delete_branch";
+    readonly renameBranch: "vcs.rename_branch";
+    readonly mergeIntoCurrent: "vcs.merge_into_current";
+    readonly mergeAbort: "vcs.merge_abort";
+    readonly mergeContinue: "vcs.merge_continue";
+    readonly isMergeInProgress: "vcs.is_merge_in_progress";
+    readonly setBranchUpstream: "vcs.set_branch_upstream";
+    readonly getBranchUpstream: "vcs.get_branch_upstream";
+    readonly hardResetHead: "vcs.hard_reset_head";
+    readonly resetSoftTo: "vcs.reset_soft_to";
+    readonly getIdentity: "vcs.get_identity";
+    readonly setIdentityLocal: "vcs.set_identity_local";
+    readonly listStashes: "vcs.list_stashes";
+    readonly stashPush: "vcs.stash_push";
+    readonly stashApply: "vcs.stash_apply";
+    readonly stashPop: "vcs.stash_pop";
+    readonly stashDrop: "vcs.stash_drop";
+    readonly stashShow: "vcs.stash_show";
+    readonly cherryPick: "vcs.cherry_pick";
+    readonly revertCommit: "vcs.revert_commit";
+};
+/** Resolves the RPC method implemented by one class-friendly delegate method. */
+export type VcsDelegateRpcMethodName<TMethodName extends VcsDelegateMethodName> = (typeof VCS_DELEGATE_METHOD_MAPPINGS)[TMethodName];
+/** Describes the callable prototype surface required by `toDelegates()`. */
+export type VcsDelegatePrototype<TContext> = {
+    [TMethodName in keyof VcsDelegateBindings<TContext>]: VcsDelegateBindings<TContext>[TMethodName];
+};
+/** Stores the exact `vcs.*` delegate object shape produced from class methods. */
+export type VcsDelegateAssignments<TContext> = {
+    [TMethodName in VcsDelegateMethodName as VcsDelegateRpcMethodName<TMethodName>]?: VcsDelegateBindings<TContext>[TMethodName];
+};

package/lib/runtime/vcs-delegate-metadata.js

@@ -0,0 +1,58 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VCS_DELEGATE_METHOD_MAPPINGS = void 0;
+/** Maps one delegate class method to the SDK runtime RPC key it implements. */
+exports.VCS_DELEGATE_METHOD_MAPPINGS = {
+    getCaps: 'vcs.get_caps',
+    open: 'vcs.open',
+    close: 'vcs.close',
+    cloneRepo: 'vcs.clone_repo',
+    getWorkdir: 'vcs.get_workdir',
+    getCurrentBranch: 'vcs.get_current_branch',
+    listBranches: 'vcs.list_branches',
+    listLocalBranches: 'vcs.list_local_branches',
+    createBranch: 'vcs.create_branch',
+    checkoutBranch: 'vcs.checkout_branch',
+    ensureRemote: 'vcs.ensure_remote',
+    listRemotes: 'vcs.list_remotes',
+    removeRemote: 'vcs.remove_remote',
+    fetch: 'vcs.fetch',
+    fetchWithOptions: 'vcs.fetch_with_options',
+    push: 'vcs.push',
+    pullFfOnly: 'vcs.pull_ff_only',
+    commit: 'vcs.commit',
+    commitIndex: 'vcs.commit_index',
+    getStatusSummary: 'vcs.get_status_summary',
+    getStatusPayload: 'vcs.get_status_payload',
+    listCommits: 'vcs.list_commits',
+    diffFile: 'vcs.diff_file',
+    diffCommit: 'vcs.diff_commit',
+    getConflictDetails: 'vcs.get_conflict_details',
+    checkoutConflictSide: 'vcs.checkout_conflict_side',
+    writeMergeResult: 'vcs.write_merge_result',
+    stagePatch: 'vcs.stage_patch',
+    discardPaths: 'vcs.discard_paths',
+    applyReversePatch: 'vcs.apply_reverse_patch',
+    deleteBranch: 'vcs.delete_branch',
+    renameBranch: 'vcs.rename_branch',
+    mergeIntoCurrent: 'vcs.merge_into_current',
+    mergeAbort: 'vcs.merge_abort',
+    mergeContinue: 'vcs.merge_continue',
+    isMergeInProgress: 'vcs.is_merge_in_progress',
+    setBranchUpstream: 'vcs.set_branch_upstream',
+    getBranchUpstream: 'vcs.get_branch_upstream',
+    hardResetHead: 'vcs.hard_reset_head',
+    resetSoftTo: 'vcs.reset_soft_to',
+    getIdentity: 'vcs.get_identity',
+    setIdentityLocal: 'vcs.set_identity_local',
+    listStashes: 'vcs.list_stashes',
+    stashPush: 'vcs.stash_push',
+    stashApply: 'vcs.stash_apply',
+    stashPop: 'vcs.stash_pop',
+    stashDrop: 'vcs.stash_drop',
+    stashShow: 'vcs.stash_show',
+    cherryPick: 'vcs.cherry_pick',
+    revertCommit: 'vcs.revert_commit',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "OpenVCS SDK CLI for plugin scaffolding and .ovcsp tar.gz packaging",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",
@@ -32,7 +32,8 @@
   },
   "scripts": {
     "build": "node scripts/build-sdk.js",
-    "test": "npm run build && node --test test/*.test.js",
+    "test": "npm run build && npm run test:types && node --test test/*.test.js",
+    "test:types": "node ./node_modules/typescript/bin/tsc -p test/tsconfig.json",
     "prepack": "npm run build",
     "preopenvcs": "npm run build",
     "openvcs": "node bin/openvcs.js"