@openvcs/sdk 0.4.0 → 0.4.1-beta.128

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.4.0",
+  "version": "0.4.1-beta.128",
   "description": "OpenVCS SDK CLI for plugin scaffolding and runtime asset builds",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",
@@ -12,7 +12,7 @@
     "url": "https://github.com/Open-VCS/OpenVCS-SDK/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "bin": {
     "openvcs": "bin/openvcs.js"
@@ -32,7 +32,9 @@
   },
   "scripts": {
     "build": "node scripts/build-sdk.js",
-    "test": "npm run build && npm run test:types && node --test test/*.test.js",
+    "test": "npm run build && npm run test:types && node scripts/run-tests.js",
+    "coverage": "npm run build && npm run test:types && c8 --check-coverage --lines 95 --functions 95 --branches 85 --statements 95 --reporter=text --reporter=lcov node scripts/run-tests.js",
+    "test:coverage": "npm run coverage",
     "test:types": "node ./node_modules/typescript/bin/tsc -p test/tsconfig.json",
     "prepack": "npm run build",
     "preopenvcs": "npm run build",
@@ -40,6 +42,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.3.3",
+    "c8": "^11.0.0",
     "typescript": "^6.0.3"
   },
   "files": [

package/src/lib/build.ts

@@ -6,6 +6,9 @@ import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 
 import { isPathInside } from "./fs-utils";
+import { npmArgsPrefix, npmExecutable } from "./npm-runner";
+
+export { npmExecutable } from "./npm-runner";
 
 type UsageError = Error & { code?: string };
 
@@ -23,6 +26,10 @@ export interface ManifestInfo {
   manifestPath: string;
 }
 
+function writeBuildProgress(message: string): void {
+  process.stderr.write(`openvcs build: ${message}\n`);
+}
+
 interface CommandResult {
   status: number | null;
   error?: Error;
@@ -34,21 +41,6 @@ interface PackageScripts {
 
 const AUTHORED_PLUGIN_MODULE_BASENAME = "plugin.js";
 
-/** Returns the npm executable name for the current platform. */
-export function npmExecutable(): string {
-  return "npm";
-}
-
-/** Returns whether a command must be launched via the Windows shell. */
-export function shouldUseWindowsShell(program: string): boolean {
-  if (process.platform !== "win32") {
-    return false;
-  }
-
-  const normalized = program.toLowerCase();
-  return normalized === "npm" || normalized.endsWith(".cmd") || normalized.endsWith(".bat");
-}
-
 /** Formats help text for the build command. */
 export function buildUsage(commandName = "openvcs"): string {
   return `${commandName} build [args]\n\n  --plugin-dir <path>   Plugin repository root (contains package.json with openvcs metadata)\n  -V, --verbose         Enable verbose output\n`;
@@ -88,11 +80,14 @@ export function parseBuildArgs(args: string[]): BuildArgs {
 }
 
 /** Reads and validates the plugin manifest. */
-export function readManifest(pluginDir: string): ManifestInfo {
+export function readManifest(pluginDir: string, verbose = false): ManifestInfo {
   const manifestPath = path.join(pluginDir, "package.json");
   let manifestRaw: string;
   let manifestFd: number | undefined;
   let manifest: unknown;
+  if (verbose) {
+    writeBuildProgress(`reading manifest at ${manifestPath}`);
+  }
   try {
     manifestFd = fs.openSync(manifestPath, "r");
     const manifestStat = fs.fstatSync(manifestFd);
@@ -142,6 +137,10 @@ export function readManifest(pluginDir: string): ManifestInfo {
   const entryValue = openvcs.entry;
   const entry = typeof entryValue === "string" ? entryValue.trim() : undefined;
 
+  if (verbose) {
+    writeBuildProgress(`manifest loaded for ${pluginId}${moduleExec ? ` (module.exec: ${moduleExec})` : ""}`);
+  }
+
   return {
     pluginId,
     moduleExec,
@@ -151,12 +150,19 @@ export function readManifest(pluginDir: string): ManifestInfo {
 }
 
 /** Verifies that a declared module entry resolves to a real file under `bin/`. */
-export function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined): void {
+export function validateDeclaredModuleExec(
+  pluginDir: string,
+  moduleExec: string | undefined,
+  verbose = false,
+): void {
   if (!moduleExec) {
     return;
   }
 
   const targetPath = resolveDeclaredModuleExecPath(pluginDir, moduleExec);
+  if (verbose) {
+    writeBuildProgress(`checking declared bootstrap at ${targetPath}`);
+  }
   if (!fs.existsSync(targetPath) || !fs.lstatSync(targetPath).isFile()) {
     throw new Error(`module entrypoint not found at ${targetPath}`);
   }
@@ -191,11 +197,15 @@ export function authoredPluginModulePath(pluginDir: string): string {
 export function validateGeneratedBootstrapTargets(
   pluginDir: string,
   moduleExec: string | undefined,
+  verbose = false,
 ): void {
   if (!moduleExec) {
     return;
   }
 
+  if (verbose) {
+    writeBuildProgress(`validating generated bootstrap target for ${moduleExec}`);
+  }
   resolveDeclaredModuleExecPath(pluginDir, moduleExec);
   const normalizedExec = moduleExec.trim().toLowerCase();
   if (normalizedExec === AUTHORED_PLUGIN_MODULE_BASENAME.toLowerCase()) {
@@ -242,18 +252,28 @@ export function renderGeneratedBootstrap(
 }
 
 /** Writes the generated SDK-owned module entrypoint under `bin/<module.exec>`. */
-export function generateModuleBootstrap(pluginDir: string, moduleExec: string | undefined): void {
+export function generateModuleBootstrap(
+  pluginDir: string,
+  moduleExec: string | undefined,
+  verbose = false,
+): void {
   if (!moduleExec) {
-    console.debug(`generateModuleBootstrap: no module.exec defined, skipping bootstrap generation for ${pluginDir}`);
+    if (verbose) {
+      writeBuildProgress(`no module.exec defined for ${pluginDir}; skipping bootstrap generation`);
+    }
     return;
   }
 
-  validateGeneratedBootstrapTargets(pluginDir, moduleExec);
+  validateGeneratedBootstrapTargets(pluginDir, moduleExec, verbose);
   const execPath = resolveDeclaredModuleExecPath(pluginDir, moduleExec);
   const pluginModulePath = authoredPluginModulePath(pluginDir);
   const pluginModuleImportPath = relativeBinImport(execPath, pluginModulePath);
   const isEsm = detectEsmMode(pluginDir, moduleExec);
 
+  if (verbose) {
+    writeBuildProgress(`writing bootstrap ${execPath} -> ${pluginModuleImportPath}${isEsm ? " (esm)" : " (cjs)"}`);
+  }
+
   fs.mkdirSync(path.dirname(execPath), { recursive: true });
   fs.writeFileSync(execPath, renderGeneratedBootstrap(pluginModuleImportPath, isEsm), "utf8");
 }
@@ -288,8 +308,8 @@ export function runCommand(program: string, args: string[], cwd: string, verbose
 
   const result = spawnSync(program, args, {
     cwd,
-    shell: shouldUseWindowsShell(program),
     stdio: ["ignore", verbose ? "inherit" : "ignore", "inherit"],
+    windowsHide: true,
   }) as CommandResult;
 
   if (result.error) {
@@ -325,11 +345,14 @@ function readPackageScripts(pluginDir: string): PackageScripts {
 
 /** Builds a plugin's runtime assets when it declares a code module. */
 export function buildPluginAssets(parsedArgs: BuildArgs): ManifestInfo {
-  const manifest = readManifest(parsedArgs.pluginDir);
+  writeBuildProgress(`reading plugin manifest in ${parsedArgs.pluginDir}`);
+  const manifest = readManifest(parsedArgs.pluginDir, parsedArgs.verbose);
   if (!manifest.moduleExec) {
+    writeBuildProgress(`theme-only plugin ${manifest.pluginId}; nothing to build`);
     return manifest;
   }
 
+  writeBuildProgress(`building plugin ${manifest.pluginId}`);
   if (!hasPackageJson(parsedArgs.pluginDir)) {
     throw new Error(`code plugins must include package.json: ${path.join(parsedArgs.pluginDir, "package.json")}`);
   }
@@ -342,8 +365,12 @@ export function buildPluginAssets(parsedArgs: BuildArgs): ManifestInfo {
     );
   }
 
-  runCommand(npmExecutable(), ["run", "build:plugin"], parsedArgs.pluginDir, parsedArgs.verbose);
-  generateModuleBootstrap(parsedArgs.pluginDir, manifest.moduleExec);
-  validateDeclaredModuleExec(parsedArgs.pluginDir, manifest.moduleExec);
+  writeBuildProgress(`running build:plugin`);
+  runCommand(npmExecutable(), [...npmArgsPrefix(), "run", "build:plugin"], parsedArgs.pluginDir, parsedArgs.verbose);
+  writeBuildProgress(`generating bootstrap ${manifest.moduleExec}`);
+  generateModuleBootstrap(parsedArgs.pluginDir, manifest.moduleExec, parsedArgs.verbose);
+  writeBuildProgress(`validating bootstrap ${manifest.moduleExec}`);
+  validateDeclaredModuleExec(parsedArgs.pluginDir, manifest.moduleExec, parsedArgs.verbose);
+  writeBuildProgress(`build complete for ${manifest.pluginId}`);
   return manifest;
 }

package/src/lib/init.ts

@@ -4,6 +4,8 @@ import * as readline from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { spawnSync } from "node:child_process";
 
+import { npmArgsPrefix, npmExecutable } from "./npm-runner";
+
 const packageJson: { version: string } = require("../package.json");
 
 type UsageError = Error & { code?: string };
@@ -33,19 +35,6 @@ interface InitCommandError {
   code?: string;
 }
 
-function npmExecutable(): string {
-  return "npm";
-}
-
-function shouldUseWindowsShell(program: string): boolean {
-  if (process.platform !== "win32") {
-    return false;
-  }
-
-  const normalized = program.toLowerCase();
-  return normalized === "npm" || normalized.endsWith(".cmd") || normalized.endsWith(".bat");
-}
-
 export function initUsage(commandName = "openvcs"): string {
   return `Usage: ${commandName} init [--theme] [target-dir]\n\nOptions:\n  --theme                Start with a theme-only plugin template\n`;
 }
@@ -214,10 +203,10 @@ async function collectAnswers(
 }
 
 function runNpmInstall(targetDir: string): void {
-  const result = spawnSync(npmExecutable(), ["install"], {
+  const result = spawnSync(npmExecutable(), [...npmArgsPrefix(), "install"], {
     cwd: targetDir,
-    shell: shouldUseWindowsShell(npmExecutable()),
     stdio: "inherit",
+    windowsHide: true,
   });
   if (result.error) {
     throw new Error(`failed to spawn npm install in ${targetDir}: ${result.error.message}`);
@@ -241,7 +230,6 @@ function writeModuleTemplate(answers: InitAnswers): void {
     openvcs: {
       id: answers.pluginId,
       name: answers.pluginName,
-      version: answers.pluginVersion,
       default_enabled: answers.defaultEnabled,
       module: { exec: "openvcs-plugin.js" },
     },
@@ -286,7 +274,6 @@ function writeThemeTemplate(answers: InitAnswers): void {
     openvcs: {
       id: answers.pluginId,
       name: answers.pluginName,
-      version: answers.pluginVersion,
       default_enabled: answers.defaultEnabled,
     },
     scripts: {
@@ -376,8 +363,10 @@ export function isUsageError(error: unknown): error is InitCommandError {
 export const __private = {
   collectAnswers,
   createReadlinePromptDriver,
+  defaultPluginNameFromId,
   defaultPluginIdFromDir,
   sanitizeIdToken,
   validatePluginId,
   writeModuleTemplate,
+  writeThemeTemplate,
 };

package/src/lib/npm-runner.ts

@@ -0,0 +1,47 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+type ExistsFn = (path: string) => boolean;
+type ResolveFn = (specifier: string) => string;
+
+export interface NpmCommand {
+  program: string;
+  argsPrefix: string[];
+}
+
+export function resolveNpmCli(
+  execPath = process.execPath,
+  exists: ExistsFn = fs.existsSync,
+  resolve: ResolveFn = require.resolve,
+): string {
+  const localNodeModules = path.join(path.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  if (exists(localNodeModules)) {
+    return localNodeModules;
+  }
+
+  return resolve("npm/bin/npm-cli.js");
+}
+
+export function npmCommand(
+  platform = process.platform,
+  execPath = process.execPath,
+  exists: ExistsFn = fs.existsSync,
+  resolve: ResolveFn = require.resolve,
+): NpmCommand {
+  if (platform !== "win32") {
+    return { program: "npm", argsPrefix: [] };
+  }
+
+  return { program: execPath, argsPrefix: [resolveNpmCli(execPath, exists, resolve)] };
+}
+
+export function npmExecutable(): string {
+  return npmCommand().program;
+}
+
+export function npmArgsPrefix(): string[] {
+  return npmCommand().argsPrefix;
+}

package/src/lib/runtime/dispatcher.ts

@@ -133,22 +133,30 @@ export function createRuntimeDispatcher(
 
       let result: unknown;
       if (timeout && timeout > 0) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+        const timeoutPromise = new Promise<never>((_resolve, reject) => {
+          timeoutId = setTimeout(() => {
+            reject(pluginError('request-timeout', `method '${method}' timed out after ${timeout}ms`));
+          }, timeout);
+        });
         try {
-          result = await handler(params, {
-            host,
-            requestId: id,
-            method,
-          });
+          result = await Promise.race([
+            handler(params, {
+              host,
+              requestId: id,
+              method,
+            }),
+            timeoutPromise,
+          ]);
         } catch (error) {
-          clearTimeout(timeoutId);
-          if ((error as Error).name === 'AbortError') {
-            throw pluginError('request-timeout', `method '${method}' timed out after ${timeout}ms`);
+          if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
           }
           throw error;
         }
-        clearTimeout(timeoutId);
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId);
+        }
       } else {
         result = await handler(params, {
           host,

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

@@ -259,7 +259,7 @@ export abstract class VcsDelegateBase<
   diffFile(
     _params: VcsTypes.VcsDiffFileParams,
     _context: TContext,
-  ): VcsHandlerResult<string[]> {
+  ): VcsHandlerResult<VcsTypes.VcsDiffFileResponse> {
     return this.unimplemented('diffFile');
   }
 
@@ -303,6 +303,14 @@ export abstract class VcsDelegateBase<
     return this.unimplemented('stagePatch');
   }
 
+  /** Handles `vcs.stage_selections` (structured hunk/line selections). */
+  stageSelections(
+    _params: VcsTypes.VcsStageSelectionsParams,
+    _context: TContext,
+  ): VcsHandlerResult<null> {
+    return this.unimplemented('stageSelections');
+  }
+
   /** Handles `vcs.stage_paths`. */
   stagePaths(
     _params: VcsTypes.VcsStagePathsParams,

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

@@ -53,6 +53,7 @@ export type VcsDelegateBindings<TContext> = {
     VcsTypes.VcsDelegates<TContext>['vcs.write_merge_result']
   >;
   stagePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_patch']>;
+  stageSelections: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_selections']>;
   stagePaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_paths']>;
   discardPaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.discard_paths']>;
   applyReversePatch: NonNullable<
@@ -123,6 +124,7 @@ export const VCS_DELEGATE_METHOD_MAPPINGS = {
   checkoutConflictSide: 'vcs.checkout_conflict_side',
   writeMergeResult: 'vcs.write_merge_result',
   stagePatch: 'vcs.stage_patch',
+  stageSelections: 'vcs.stage_selections',
   stagePaths: 'vcs.stage_paths',
   discardPaths: 'vcs.discard_paths',
   applyReversePatch: 'vcs.apply_reverse_patch',

package/src/lib/types/vcs.ts

@@ -17,6 +17,8 @@ export interface VcsCapabilities {
   push_pull: boolean;
   /** Indicates whether fast-forward helpers are supported. */
   fast_forward: boolean;
+  /** Merge strategies the backend supports (values like "merge", "squash", "rebase"). */
+  merge_strategies?: string[];
 }
 
 /** Describes params that carry a repository session id. */
@@ -110,20 +112,13 @@ export interface VcsRemoveRemoteParams extends VcsSessionParams {
   name: string;
 }
 
-/** Describes optional fetch flags. */
-export interface VcsFetchOptions {
-  /** Indicates whether stale remote references should be pruned. */
-  prune?: boolean;
-}
-
 /** Describes params for fetch methods. */
+
 export interface VcsFetchParams extends VcsSessionParams {
   /** Stores the remote to fetch when one is supplied. */
   remote?: string;
   /** Stores the refspec to fetch when one is supplied. */
   refspec?: string;
-  /** Stores optional fetch flags. */
-  opts?: VcsFetchOptions;
 }
 
 /** Describes params for push. */
@@ -180,6 +175,8 @@ export interface StatusFileEntry {
   resolved_conflict: boolean;
   /** Stores placeholder hunk information until richer diff support exists. */
   hunks: never[];
+  /** Indicates whether the file content should be treated as binary. */
+  binary?: boolean | null;
 }
 
 /** Describes the structured status payload returned to the host. */
@@ -256,6 +253,17 @@ export interface VcsDiffCommitParams extends VcsSessionParams {
   rev: string;
 }
 
+/** Describes one structured diff payload returned for a file. */
+export interface VcsDiffResult {
+  /** Stores line-oriented diff output. */
+  lines: string[];
+  /** Indicates whether the diff target should be treated as binary. */
+  binary?: boolean | null;
+}
+
+/** Describes the accepted `vcs.diff_file` response shapes. */
+export type VcsDiffFileResponse = VcsDiffResult | string[];
+
 /** Describes params for `vcs.get_conflict_details`. */
 export interface VcsGetConflictDetailsParams extends VcsSessionParams {
   /** Stores the conflicted path. */
@@ -274,8 +282,6 @@ export interface VcsConflictDetails {
   theirs: string | null;
   /** Indicates whether the conflict is binary. */
   binary: boolean;
-  /** Indicates whether the conflict references Git LFS content. */
-  lfs_pointer: boolean;
 }
 
 /** Describes params for checking out one side of a conflict. */
@@ -300,6 +306,22 @@ export interface VcsStagePatchParams extends VcsSessionParams {
   patch: string;
 }
 
+/** Describes a single file's hunk/line selection for partial staging. */
+export interface HunkSelection {
+  /** Repository-relative file path. */
+  path: string;
+  /** Indices of whole hunks to include. */
+  whole_hunks: number[];
+  /** Per-hunk line selections: maps hunk index → 1-based line offsets. */
+  partial_hunks: Record<number, number[]>;
+}
+
+/** Describes params for staging structured selections (VCS-agnostic). */
+export interface VcsStageSelectionsParams extends VcsSessionParams {
+  /** Structured hunk/line selections for multiple files. */
+  selections: HunkSelection[];
+}
+
 /** Describes params for staging repository-relative paths into the index. */
 export interface VcsStagePathsParams extends VcsSessionParams {
   /** Stores the paths to stage. */
@@ -334,12 +356,17 @@ export interface VcsRenameBranchParams extends VcsSessionParams {
   new: string;
 }
 
+/** Describes the supported merge strategies. */
+export type VcsMergeStrategy = 'merge' | 'squash' | 'rebase';
+
 /** Describes params for merging another branch into the current branch. */
 export interface VcsMergeIntoCurrentParams extends VcsSessionParams {
   /** Stores the branch name to merge. */
   name: string;
   /** Stores an optional merge commit message. */
   message?: string;
+  /** Stores the merge strategy. Defaults to 'merge' when absent. */
+  strategy?: VcsMergeStrategy;
 }
 
 /** Describes params for setting a branch upstream. */
@@ -503,7 +530,7 @@ export interface VcsDelegates<TContext = unknown> {
     TContext
   >;
   /** Handles `vcs.diff_file`. */
-  'vcs.diff_file'?: RpcMethodHandler<VcsDiffFileParams, string[], TContext>;
+  'vcs.diff_file'?: RpcMethodHandler<VcsDiffFileParams, VcsDiffFileResponse, TContext>;
   /** Handles `vcs.diff_commit`. */
   'vcs.diff_commit'?: RpcMethodHandler<VcsDiffCommitParams, string[], TContext>;
   /** Handles `vcs.get_conflict_details`. */
@@ -526,6 +553,8 @@ export interface VcsDelegates<TContext = unknown> {
   >;
   /** Handles `vcs.stage_patch`. */
   'vcs.stage_patch'?: RpcMethodHandler<VcsStagePatchParams, null, TContext>;
+  /** Handles `vcs.stage_selections` (structured hunk/line selections). */
+  'vcs.stage_selections'?: RpcMethodHandler<VcsStageSelectionsParams, null, TContext>;
   /** Handles `vcs.stage_paths`. */
   'vcs.stage_paths'?: RpcMethodHandler<VcsStagePathsParams, null, TContext>;
   /** Handles `vcs.discard_paths`. */