@openvcs/sdk 0.2.5 → 0.2.7

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

@@ -0,0 +1,165 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+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 const 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',
+} as const satisfies Record<
+  VcsDelegateMethodName,
+  keyof VcsTypes.VcsDelegates<PluginRuntimeContext>
+>;
+
+/** 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/src/lib/types/vcs.ts

@@ -238,6 +238,8 @@ export interface CommitEntry {
   author: string;
   /** Stores the formatted metadata string. */
   meta: string;
+  /** Stores the first parent commit id when available. */
+  parent_oid?: string;
 }
 
 /** Describes params for `vcs.diff_file`. */
@@ -352,6 +354,18 @@ export interface VcsResetSoftToParams extends VcsSessionParams {
   rev: string;
 }
 
+/** Describes params for continuing a merge in progress. */
+export interface VcsMergeContinueParams extends VcsSessionParams {
+  /** Stores an optional commit message override. */
+  message?: string;
+}
+
+/** Describes params for hard resetting HEAD to a given ref. */
+export interface VcsHardResetHeadParams extends VcsSessionParams {
+  /** Stores the ref to reset HEAD to; defaults to HEAD. */
+  ref?: string;
+}
+
 /** Describes one configured author identity. */
 export interface VcsIdentity {
   /** Stores the configured author name. */
@@ -525,7 +539,7 @@ export interface VcsDelegates<TContext = unknown> {
   /** Handles `vcs.merge_abort`. */
   'vcs.merge_abort'?: RpcMethodHandler<VcsSessionParams, null, TContext>;
   /** Handles `vcs.merge_continue`. */
-  'vcs.merge_continue'?: RpcMethodHandler<VcsSessionParams, null, TContext>;
+  'vcs.merge_continue'?: RpcMethodHandler<VcsMergeContinueParams, null, TContext>;
   /** Handles `vcs.is_merge_in_progress`. */
   'vcs.is_merge_in_progress'?: RpcMethodHandler<
     VcsSessionParams,
@@ -545,7 +559,7 @@ export interface VcsDelegates<TContext = unknown> {
     TContext
   >;
   /** Handles `vcs.hard_reset_head`. */
-  'vcs.hard_reset_head'?: RpcMethodHandler<VcsSessionParams, null, TContext>;
+  'vcs.hard_reset_head'?: RpcMethodHandler<VcsHardResetHeadParams, null, TContext>;
   /** Handles `vcs.reset_soft_to`. */
   'vcs.reset_soft_to'?: RpcMethodHandler<VcsResetSoftToParams, null, TContext>;
   /** Handles `vcs.get_identity`. */

package/test/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".."
+  },
+  "include": ["../src/**/*.ts", "./vcs-delegate-base.types.ts", "./vcs-delegate-base.test.ts"]
+}

package/test/vcs-delegate-base.test.js

@@ -0,0 +1,169 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+const { VcsDelegateBase } = require('../lib/runtime');
+
+/**
+ * Compile-time override safety lives in `vcs-delegate-base.types.ts`, which
+ * verifies that generic parameters are explicit and incompatible signatures
+ * (wrong return type or params) fail the TypeScript compiler.  This file
+ * tests runtime behavior using the plain Node test runner.
+ * @typedef {{ message: string, method: string }} CommitCall */
+
+class ExampleVcsDelegates extends VcsDelegateBase {
+  /** @param {{ prefix: string, calls: CommitCall[] }} deps */
+  constructor(deps) {
+    super(deps);
+  }
+
+  getCaps() {
+    return {
+      commits: true,
+      branches: true,
+      tags: false,
+      staging: true,
+      push_pull: false,
+      fast_forward: true,
+    };
+  }
+
+  async commit(params, context) {
+    this.deps.calls.push({ message: params.message, method: context.method });
+    return `${this.deps.prefix}:${params.message}`;
+  }
+}
+
+class SharedBranchDelegates extends VcsDelegateBase {
+  /** @param {{}} deps */
+  constructor(deps) {
+    super(deps);
+  }
+
+  getCurrentBranch(params) {
+    return `branch:${params.session_id}`;
+  }
+}
+
+class DerivedBranchDelegates extends SharedBranchDelegates {
+  listBranches() {
+    return [];
+  }
+}
+
+test('VcsDelegateBase maps overridden camelCase methods to rpc delegates', async () => {
+  const delegate = new ExampleVcsDelegates({ prefix: 'commit', calls: [] });
+  const delegates = delegate.toDelegates();
+
+  assert.deepEqual(Object.keys(delegates).sort(), ['vcs.commit', 'vcs.get_caps']);
+  assert.equal(typeof delegates['vcs.get_caps'], 'function');
+  assert.equal(typeof delegates['vcs.commit'], 'function');
+
+  assert.deepEqual(await delegates['vcs.get_caps']({}, {}), {
+    commits: true,
+    branches: true,
+    tags: false,
+    staging: true,
+    push_pull: false,
+    fast_forward: true,
+  });
+
+  assert.equal(
+    await delegates['vcs.commit'](
+      {
+        session_id: 'session-1',
+        name: 'OpenVCS',
+        email: 'team@example.com',
+        message: 'ship it',
+      },
+      { host: {}, method: 'vcs.commit', requestId: 7 },
+    ),
+    'commit:ship it',
+  );
+  assert.deepEqual(delegate.deps.calls, [
+    { message: 'ship it', method: 'vcs.commit' },
+  ]);
+});
+
+test('VcsDelegateBase keeps inherited overrides when building delegates', async () => {
+  const delegates = new DerivedBranchDelegates({}).toDelegates();
+
+  assert.deepEqual(Object.keys(delegates).sort(), [
+    'vcs.get_current_branch',
+    'vcs.list_branches',
+  ]);
+  assert.equal(
+    await delegates['vcs.get_current_branch'](
+      { session_id: 'session-2' },
+      { host: {}, method: 'vcs.get_current_branch', requestId: 8 },
+    ),
+    'branch:session-2',
+  );
+  assert.deepEqual(
+    await delegates['vcs.list_branches'](
+      { session_id: 'session-2' },
+      { host: {}, method: 'vcs.list_branches', requestId: 9 },
+    ),
+    [],
+  );
+});
+
+test('VcsDelegateBase returns a fresh delegate map on each call', async () => {
+  const delegate = new ExampleVcsDelegates({ prefix: 'repeat', calls: [] });
+  const firstDelegates = delegate.toDelegates();
+  const secondDelegates = delegate.toDelegates();
+
+  assert.notStrictEqual(firstDelegates, secondDelegates);
+  assert.notStrictEqual(
+    firstDelegates['vcs.commit'],
+    secondDelegates['vcs.commit'],
+  );
+  assert.equal(
+    await secondDelegates['vcs.commit'](
+      {
+        session_id: 'session-3',
+        name: 'OpenVCS',
+        email: 'team@example.com',
+        message: 'again',
+      },
+      { host: {}, method: 'vcs.commit', requestId: 10 },
+    ),
+    'repeat:again',
+  );
+});
+
+test('VcsDelegateBase throws with the exact error message for base stubs', () => {
+  const delegate = new ExampleVcsDelegates({ prefix: 'x', calls: [] });
+
+  // Each base stub throws with a message that includes the method name.
+  // Test a representative subset; all stubs share the same formatter.
+  const expectedMessage = "VCS delegate method 'cloneRepo' must be overridden before registration";
+  let thrown;
+  try {
+    delegate.cloneRepo({ url: 'x', dest: 'y' }, {});
+  } catch (e) {
+    thrown = e;
+  }
+  assert.ok(thrown instanceof Error, 'should throw an Error');
+  assert.strictEqual(thrown.message, expectedMessage);
+
+  // Verify a second stub throws with its own method name in the message.
+  const expectedMessage2 = "VCS delegate method 'stashPush' must be overridden before registration";
+  let thrown2;
+  try {
+    delegate.stashPush({ session_id: 's' }, {});
+  } catch (e) {
+    thrown2 = e;
+  }
+  assert.ok(thrown2 instanceof Error);
+  assert.strictEqual(thrown2.message, expectedMessage2);
+});
+
+test('VcsDelegateBase accepts an empty deps object without errors', () => {
+  assert.doesNotThrow(() => new ExampleVcsDelegates({ prefix: '', calls: [] }));
+  assert.doesNotThrow(() => new SharedBranchDelegates({}));
+  const delegates = new SharedBranchDelegates({}).toDelegates();
+  assert.deepEqual(Object.keys(delegates), ['vcs.get_current_branch']);
+});

package/test/vcs-delegate-base.types.ts

@@ -0,0 +1,44 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type { RequestParams, VcsCapabilities } from '../src/lib/types';
+
+import {
+  VcsDelegateBase,
+  type PluginRuntimeContext,
+} from '../src/lib/runtime';
+
+type CommitCall = {
+  message: string;
+  method: string;
+};
+
+class TypedExampleVcsDelegates extends VcsDelegateBase<{
+  prefix: string;
+  calls: CommitCall[];
+}> {
+  override getCaps(
+    _params: RequestParams,
+    _context: PluginRuntimeContext,
+  ): VcsCapabilities {
+    return {
+      commits: true,
+      branches: true,
+      tags: false,
+      staging: true,
+      push_pull: false,
+      fast_forward: true,
+    };
+  }
+}
+
+new TypedExampleVcsDelegates({ prefix: 'commit', calls: [] }).toDelegates();
+
+class InvalidVcsDelegates extends VcsDelegateBase<{}> {
+  // @ts-expect-error `getCaps` must return `VcsCapabilities`.
+  override getCaps(): string {
+    return 'invalid';
+  }
+}
+
+new InvalidVcsDelegates({});