@openvcs/sdk 0.4.0 → 0.4.1-beta.128

package/README.md

@@ -5,6 +5,8 @@
 
 OpenVCS SDK for npm-based plugin development.
 
+Requires Node.js 20 or newer.
+
 Install this package in plugin projects, scaffold a starter plugin, and build
 plugin runtime assets. The SDK also exports a Node-only JSON-RPC runtime
 layer and shared protocol/types so plugins do not have to hand-roll stdio
@@ -41,6 +43,16 @@ Run tests (builds first):
 npm test
 ```
 
+Generate a coverage report:
+
+```bash
+npm run coverage
+```
+
+This runs the full test flow, writes c8 output to `coverage/`, and fails if
+coverage drops below 95% lines, 95% functions, 85% branches, or 95%
+statements.
+
 Run the local CLI through npm scripts:
 
 ```bash
@@ -162,6 +174,9 @@ compiled plugin author module at `bin/plugin.js`, and then generates the SDK-own
 `bin/<module.exec>` bootstrap that imports `./plugin.js`, applies `PluginDefinition`,
 invokes `OnPluginStart()`, and starts the runtime.
 
+The build prints progress messages to stderr so you can see each phase. Pass `-V`
+or `--verbose` to also echo the exact command and validation details.
+
 Theme-only plugins can also run `npm run build`; the command exits successfully
 without producing `bin/` output.
 
@@ -196,18 +211,18 @@ Dependency behavior:
 
 ## CLI usage
 
-Build a plugin manually:
+Build plugin assets from a plugin project:
 
 ```bash
-npx openvcs build --plugin-dir /path/to/plugin
+npm run build
 ```
 
-Show command help:
+Show command help through npm script:
 
 ```bash
-npx openvcs --help
-npx openvcs build --help
-npx openvcs init --help
+npm run openvcs -- --help
+npm run openvcs -- build --help
+npm run openvcs -- init --help
 ```
 
 ## Publishing Note

package/lib/build.d.ts

@@ -1,3 +1,4 @@
+export { npmExecutable } from "./npm-runner";
 /** CLI arguments for `openvcs build`. */
 export interface BuildArgs {
     pluginDir: string;
@@ -10,26 +11,22 @@ export interface ManifestInfo {
     entry: string | undefined;
     manifestPath: string;
 }
-/** Returns the npm executable name for the current platform. */
-export declare function npmExecutable(): string;
-/** Returns whether a command must be launched via the Windows shell. */
-export declare function shouldUseWindowsShell(program: string): boolean;
 /** Formats help text for the build command. */
 export declare function buildUsage(commandName?: string): string;
 /** Parses `openvcs build` arguments. */
 export declare function parseBuildArgs(args: string[]): BuildArgs;
 /** Reads and validates the plugin manifest. */
-export declare function readManifest(pluginDir: string): ManifestInfo;
+export declare function readManifest(pluginDir: string, verbose?: boolean): ManifestInfo;
 /** Verifies that a declared module entry resolves to a real file under `bin/`. */
-export declare function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined): void;
+export declare function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined, verbose?: boolean): void;
 /** Returns the compiled plugin module path imported by the generated bootstrap. */
 export declare function authoredPluginModulePath(pluginDir: string): string;
 /** Ensures the plugin's authored module and generated bootstrap paths are compatible. */
-export declare function validateGeneratedBootstrapTargets(pluginDir: string, moduleExec: string | undefined): void;
+export declare function validateGeneratedBootstrapTargets(pluginDir: string, moduleExec: string | undefined, verbose?: boolean): void;
 /** Renders the generated Node bootstrap that owns runtime startup. */
 export declare function renderGeneratedBootstrap(pluginModuleImportPath: string, isEsm: boolean): string;
 /** Writes the generated SDK-owned module entrypoint under `bin/<module.exec>`. */
-export declare function generateModuleBootstrap(pluginDir: string, moduleExec: string | undefined): void;
+export declare function generateModuleBootstrap(pluginDir: string, moduleExec: string | undefined, verbose?: boolean): void;
 /** Returns whether the plugin repository has a `package.json`. */
 export declare function hasPackageJson(pluginDir: string): boolean;
 /** Runs a command in the given directory with optional verbose logging. */

package/lib/build.js

@@ -35,8 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.npmExecutable = npmExecutable;
-exports.shouldUseWindowsShell = shouldUseWindowsShell;
+exports.npmExecutable = void 0;
 exports.buildUsage = buildUsage;
 exports.parseBuildArgs = parseBuildArgs;
 exports.readManifest = readManifest;
@@ -52,19 +51,13 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const fs_utils_1 = require("./fs-utils");
-const AUTHORED_PLUGIN_MODULE_BASENAME = "plugin.js";
-/** Returns the npm executable name for the current platform. */
-function npmExecutable() {
-    return "npm";
-}
-/** Returns whether a command must be launched via the Windows shell. */
-function shouldUseWindowsShell(program) {
-    if (process.platform !== "win32") {
-        return false;
-    }
-    const normalized = program.toLowerCase();
-    return normalized === "npm" || normalized.endsWith(".cmd") || normalized.endsWith(".bat");
+const npm_runner_1 = require("./npm-runner");
+var npm_runner_2 = require("./npm-runner");
+Object.defineProperty(exports, "npmExecutable", { enumerable: true, get: function () { return npm_runner_2.npmExecutable; } });
+function writeBuildProgress(message) {
+    process.stderr.write(`openvcs build: ${message}\n`);
 }
+const AUTHORED_PLUGIN_MODULE_BASENAME = "plugin.js";
 /** Formats help text for the build command. */
 function buildUsage(commandName = "openvcs") {
     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`;
@@ -100,11 +93,14 @@ function parseBuildArgs(args) {
     };
 }
 /** Reads and validates the plugin manifest. */
-function readManifest(pluginDir) {
+function readManifest(pluginDir, verbose = false) {
     const manifestPath = path.join(pluginDir, "package.json");
     let manifestRaw;
     let manifestFd;
     let manifest;
+    if (verbose) {
+        writeBuildProgress(`reading manifest at ${manifestPath}`);
+    }
     try {
         manifestFd = fs.openSync(manifestPath, "r");
         const manifestStat = fs.fstatSync(manifestFd);
@@ -148,6 +144,9 @@ function readManifest(pluginDir) {
     const moduleExec = typeof moduleValue?.exec === "string" ? moduleValue.exec.trim() : undefined;
     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,
@@ -156,11 +155,14 @@ function readManifest(pluginDir) {
     };
 }
 /** Verifies that a declared module entry resolves to a real file under `bin/`. */
-function validateDeclaredModuleExec(pluginDir, moduleExec) {
+function validateDeclaredModuleExec(pluginDir, moduleExec, verbose = false) {
     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}`);
     }
@@ -187,10 +189,13 @@ function authoredPluginModulePath(pluginDir) {
     return path.resolve(pluginDir, "bin", AUTHORED_PLUGIN_MODULE_BASENAME);
 }
 /** Ensures the plugin's authored module and generated bootstrap paths are compatible. */
-function validateGeneratedBootstrapTargets(pluginDir, moduleExec) {
+function validateGeneratedBootstrapTargets(pluginDir, moduleExec, verbose = false) {
     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()) {
@@ -221,16 +226,21 @@ function renderGeneratedBootstrap(pluginModuleImportPath, isEsm) {
     return `#!/usr/bin/env node\n// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\n(async () => {\n  const { bootstrapPluginModule } = require('@openvcs/sdk/runtime');\n  await bootstrapPluginModule({\n    importPluginModule: async () => require('${pluginModuleImportPath}'),\n    modulePath: '${pluginModuleImportPath}',\n  });\n})();\n`;
 }
 /** Writes the generated SDK-owned module entrypoint under `bin/<module.exec>`. */
-function generateModuleBootstrap(pluginDir, moduleExec) {
+function generateModuleBootstrap(pluginDir, moduleExec, verbose = false) {
     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");
 }
@@ -262,8 +272,8 @@ function runCommand(program, args, cwd, verbose) {
     }
     const result = (0, node_child_process_1.spawnSync)(program, args, {
         cwd,
-        shell: shouldUseWindowsShell(program),
         stdio: ["ignore", verbose ? "inherit" : "ignore", "inherit"],
+        windowsHide: true,
     });
     if (result.error) {
         throw new Error(`failed to spawn '${program}' in ${cwd}: ${result.error.message}`);
@@ -295,10 +305,13 @@ function readPackageScripts(pluginDir) {
 }
 /** Builds a plugin's runtime assets when it declares a code module. */
 function buildPluginAssets(parsedArgs) {
-    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")}`);
     }
@@ -307,8 +320,12 @@ function buildPluginAssets(parsedArgs) {
     if (typeof buildScript !== "string" || buildScript.trim() === "") {
         throw new Error(`code plugins must define scripts[\"build:plugin\"] in ${path.join(parsedArgs.pluginDir, "package.json")}`);
     }
-    runCommand(npmExecutable(), ["run", "build:plugin"], parsedArgs.pluginDir, parsedArgs.verbose);
-    generateModuleBootstrap(parsedArgs.pluginDir, manifest.moduleExec);
-    validateDeclaredModuleExec(parsedArgs.pluginDir, manifest.moduleExec);
+    writeBuildProgress(`running build:plugin`);
+    runCommand((0, npm_runner_1.npmExecutable)(), [...(0, npm_runner_1.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/lib/init.d.ts

@@ -22,18 +22,22 @@ interface InitCommandError {
 export declare function initUsage(commandName?: string): string;
 declare function sanitizeIdToken(raw: string): string;
 declare function defaultPluginIdFromDir(targetDir: string): string;
+declare function defaultPluginNameFromId(pluginId: string): string;
 declare function validatePluginId(pluginId: string): string | undefined;
 declare function createReadlinePromptDriver(output?: NodeJS.WritableStream): PromptDriver;
 declare function collectAnswers({ forceTheme, targetHint }: CollectAnswersOptions, promptDriver?: PromptDriver, output?: NodeJS.WritableStream): Promise<InitAnswers>;
 declare function writeModuleTemplate(answers: InitAnswers): void;
+declare function writeThemeTemplate(answers: InitAnswers): void;
 export declare function runInitCommand(args: string[]): Promise<string>;
 export declare function isUsageError(error: unknown): error is InitCommandError;
 export declare const __private: {
     collectAnswers: typeof collectAnswers;
     createReadlinePromptDriver: typeof createReadlinePromptDriver;
+    defaultPluginNameFromId: typeof defaultPluginNameFromId;
     defaultPluginIdFromDir: typeof defaultPluginIdFromDir;
     sanitizeIdToken: typeof sanitizeIdToken;
     validatePluginId: typeof validatePluginId;
     writeModuleTemplate: typeof writeModuleTemplate;
+    writeThemeTemplate: typeof writeThemeTemplate;
 };
 export {};

package/lib/init.js

@@ -42,17 +42,8 @@ const path = __importStar(require("node:path"));
 const readline = __importStar(require("node:readline/promises"));
 const node_process_1 = require("node:process");
 const node_child_process_1 = require("node:child_process");
+const npm_runner_1 = require("./npm-runner");
 const packageJson = require("../package.json");
-function npmExecutable() {
-    return "npm";
-}
-function shouldUseWindowsShell(program) {
-    if (process.platform !== "win32") {
-        return false;
-    }
-    const normalized = program.toLowerCase();
-    return normalized === "npm" || normalized.endsWith(".cmd") || normalized.endsWith(".bat");
-}
 function initUsage(commandName = "openvcs") {
     return `Usage: ${commandName} init [--theme] [target-dir]\n\nOptions:\n  --theme                Start with a theme-only plugin template\n`;
 }
@@ -203,10 +194,10 @@ async function collectAnswers({ forceTheme, targetHint }, promptDriver = createR
     }
 }
 function runNpmInstall(targetDir) {
-    const result = (0, node_child_process_1.spawnSync)(npmExecutable(), ["install"], {
+    const result = (0, node_child_process_1.spawnSync)((0, npm_runner_1.npmExecutable)(), [...(0, npm_runner_1.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}`);
@@ -228,7 +219,6 @@ function writeModuleTemplate(answers) {
         openvcs: {
             id: answers.pluginId,
             name: answers.pluginName,
-            version: answers.pluginVersion,
             default_enabled: answers.defaultEnabled,
             module: { exec: "openvcs-plugin.js" },
         },
@@ -269,7 +259,6 @@ function writeThemeTemplate(answers) {
         openvcs: {
             id: answers.pluginId,
             name: answers.pluginName,
-            version: answers.pluginVersion,
             default_enabled: answers.defaultEnabled,
         },
         scripts: {
@@ -350,8 +339,10 @@ function isUsageError(error) {
 exports.__private = {
     collectAnswers,
     createReadlinePromptDriver,
+    defaultPluginNameFromId,
     defaultPluginIdFromDir,
     sanitizeIdToken,
     validatePluginId,
     writeModuleTemplate,
+    writeThemeTemplate,
 };

package/lib/npm-runner.d.ts

@@ -0,0 +1,11 @@
+type ExistsFn = (path: string) => boolean;
+type ResolveFn = (specifier: string) => string;
+export interface NpmCommand {
+    program: string;
+    argsPrefix: string[];
+}
+export declare function resolveNpmCli(execPath?: string, exists?: ExistsFn, resolve?: ResolveFn): string;
+export declare function npmCommand(platform?: NodeJS.Platform, execPath?: string, exists?: ExistsFn, resolve?: ResolveFn): NpmCommand;
+export declare function npmExecutable(): string;
+export declare function npmArgsPrefix(): string[];
+export {};

package/lib/npm-runner.js

@@ -0,0 +1,62 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveNpmCli = resolveNpmCli;
+exports.npmCommand = npmCommand;
+exports.npmExecutable = npmExecutable;
+exports.npmArgsPrefix = npmArgsPrefix;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+function resolveNpmCli(execPath = process.execPath, exists = fs.existsSync, resolve = require.resolve) {
+    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");
+}
+function npmCommand(platform = process.platform, execPath = process.execPath, exists = fs.existsSync, resolve = require.resolve) {
+    if (platform !== "win32") {
+        return { program: "npm", argsPrefix: [] };
+    }
+    return { program: execPath, argsPrefix: [resolveNpmCli(execPath, exists, resolve)] };
+}
+function npmExecutable() {
+    return npmCommand().program;
+}
+function npmArgsPrefix() {
+    return npmCommand().argsPrefix;
+}

package/lib/runtime/dispatcher.js

@@ -83,23 +83,31 @@ function createRuntimeDispatcher(options, host, writer) {
             }
             let result;
             if (timeout && timeout > 0) {
-                const controller = new AbortController();
-                const timeoutId = setTimeout(() => controller.abort(), timeout);
+                let timeoutId;
+                const timeoutPromise = new Promise((_resolve, reject) => {
+                    timeoutId = setTimeout(() => {
+                        reject((0, errors_1.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.name === 'AbortError') {
-                        throw (0, errors_1.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, {

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

@@ -66,7 +66,7 @@ export declare abstract class VcsDelegateBase<TDeps, TContext = PluginRuntimeCon
     /** 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[]>;
+    diffFile(_params: VcsTypes.VcsDiffFileParams, _context: TContext): VcsHandlerResult<VcsTypes.VcsDiffFileResponse>;
     /** Handles `vcs.diff_commit`. */
     diffCommit(_params: VcsTypes.VcsDiffCommitParams, _context: TContext): VcsHandlerResult<string[]>;
     /** Handles `vcs.get_conflict_details`. */
@@ -77,6 +77,8 @@ export declare abstract class VcsDelegateBase<TDeps, TContext = PluginRuntimeCon
     writeMergeResult(_params: VcsTypes.VcsWriteMergeResultParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.stage_patch`. */
     stagePatch(_params: VcsTypes.VcsStagePatchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.stage_selections` (structured hunk/line selections). */
+    stageSelections(_params: VcsTypes.VcsStageSelectionsParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.stage_paths`. */
     stagePaths(_params: VcsTypes.VcsStagePathsParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.discard_paths`. */

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

@@ -157,6 +157,10 @@ class VcsDelegateBase {
     stagePatch(_params, _context) {
         return this.unimplemented('stagePatch');
     }
+    /** Handles `vcs.stage_selections` (structured hunk/line selections). */
+    stageSelections(_params, _context) {
+        return this.unimplemented('stageSelections');
+    }
     /** Handles `vcs.stage_paths`. */
     stagePaths(_params, _context) {
         return this.unimplemented('stagePaths');

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

@@ -30,6 +30,7 @@ export type VcsDelegateBindings<TContext> = {
     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']>;
+    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<VcsTypes.VcsDelegates<TContext>['vcs.apply_reverse_patch']>;
@@ -86,6 +87,7 @@ export declare const VCS_DELEGATE_METHOD_MAPPINGS: {
     readonly checkoutConflictSide: "vcs.checkout_conflict_side";
     readonly writeMergeResult: "vcs.write_merge_result";
     readonly stagePatch: "vcs.stage_patch";
+    readonly stageSelections: "vcs.stage_selections";
     readonly stagePaths: "vcs.stage_paths";
     readonly discardPaths: "vcs.discard_paths";
     readonly applyReversePatch: "vcs.apply_reverse_patch";

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

@@ -33,6 +33,7 @@ exports.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/lib/types/vcs.d.ts

@@ -13,6 +13,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. */
 export interface VcsSessionParams extends RequestParams {
@@ -92,19 +94,12 @@ export interface VcsRemoveRemoteParams extends VcsSessionParams {
     /** Stores the remote name to remove. */
     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. */
 export interface VcsPushParams extends VcsSessionParams {
@@ -156,6 +151,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. */
 export interface StatusPayload {
@@ -224,6 +221,15 @@ export interface VcsDiffCommitParams extends VcsSessionParams {
     /** Stores the revision to diff. */
     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. */
@@ -241,8 +247,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. */
 export interface VcsCheckoutConflictSideParams extends VcsSessionParams {
@@ -263,6 +267,20 @@ export interface VcsStagePatchParams extends VcsSessionParams {
     /** Stores the textual patch content. */
     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. */
@@ -292,12 +310,16 @@ export interface VcsRenameBranchParams extends VcsSessionParams {
     /** Stores the next branch name. */
     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. */
 export interface VcsSetBranchUpstreamParams extends VcsSessionParams {
@@ -420,7 +442,7 @@ export interface VcsDelegates<TContext = unknown> {
     /** Handles `vcs.list_commits`. */
     'vcs.list_commits'?: RpcMethodHandler<VcsListCommitsParams, CommitEntry[], 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`. */
@@ -431,6 +453,8 @@ export interface VcsDelegates<TContext = unknown> {
     'vcs.write_merge_result'?: RpcMethodHandler<VcsWriteMergeResultParams, null, TContext>;
     /** 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`. */