@openvcs/sdk 0.4.1 → 0.4.2-edge.20260613.129

package/README.md

@@ -174,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.
 
@@ -208,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

@@ -16,17 +16,17 @@ 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

@@ -54,6 +54,9 @@ const fs_utils_1 = require("./fs-utils");
 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") {
@@ -90,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);
@@ -138,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,
@@ -146,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}`);
     }
@@ -177,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()) {
@@ -211,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");
 }
@@ -285,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")}`);
     }
@@ -297,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")}`);
     }
+    writeBuildProgress(`running build:plugin`);
     runCommand((0, npm_runner_1.npmExecutable)(), [...(0, npm_runner_1.npmArgsPrefix)(), "run", "build:plugin"], parsedArgs.pluginDir, parsedArgs.verbose);
-    generateModuleBootstrap(parsedArgs.pluginDir, manifest.moduleExec);
-    validateDeclaredModuleExec(parsedArgs.pluginDir, manifest.moduleExec);
+    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/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`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.4.1",
+  "version": "0.4.2-edge.20260613.129",
   "description": "OpenVCS SDK CLI for plugin scaffolding and runtime asset builds",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",

package/src/lib/build.ts

@@ -26,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;
@@ -76,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);
@@ -130,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,
@@ -139,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}`);
   }
@@ -179,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()) {
@@ -230,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");
 }
@@ -313,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")}`);
   }
@@ -330,8 +365,12 @@ export function buildPluginAssets(parsedArgs: BuildArgs): ManifestInfo {
     );
   }
 
+  writeBuildProgress(`running build:plugin`);
   runCommand(npmExecutable(), [...npmArgsPrefix(), "run", "build:plugin"], parsedArgs.pluginDir, parsedArgs.verbose);
-  generateModuleBootstrap(parsedArgs.pluginDir, manifest.moduleExec);
-  validateDeclaredModuleExec(parsedArgs.pluginDir, manifest.moduleExec);
+  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/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`. */

package/test/build.test.js

@@ -16,6 +16,20 @@ const {
 } = require("../lib/build");
 const { cleanupTempDir, makeTempDir, writeJson, writeText } = require("./helpers");
 
+function captureStderr(fn) {
+  const chunks = [];
+  const originalWrite = process.stderr.write;
+  process.stderr.write = (chunk) => {
+    chunks.push(String(chunk));
+    return true;
+  };
+  try {
+    return { result: fn(), stderr: chunks.join("") };
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+}
+
 test("renderGeneratedBootstrap creates ESM code", () => {
   const output = require("../lib/build").renderGeneratedBootstrap("./plugin.js", true);
   assert.match(output, /^#!/);
@@ -64,9 +78,11 @@ test("buildPluginAssets no-ops for theme-only plugins", () => {
     name: "theme-only",
     openvcs: { id: "theme-only" },
   });
-  const manifest = buildPluginAssets({ pluginDir, verbose: false });
+  const { result: manifest, stderr } = captureStderr(() => buildPluginAssets({ pluginDir, verbose: false }));
 
   assert.equal(manifest.pluginId, "theme-only");
+  assert.match(stderr, /openvcs build: reading plugin manifest/);
+  assert.match(stderr, /openvcs build: theme-only plugin theme-only; nothing to build/);
   cleanupTempDir(root);
 });
 
@@ -110,7 +126,7 @@ test("buildPluginAssets runs build:plugin and validates output", () => {
     "const fs = require('node:fs');\nconst path = require('node:path');\nconst out = path.join(process.cwd(), 'bin', 'plugin.js');\nfs.mkdirSync(path.dirname(out), { recursive: true });\nfs.writeFileSync(out, 'export {};\\n', 'utf8');\n"
   );
 
-  const manifest = buildPluginAssets({ pluginDir, verbose: false });
+  const { result: manifest, stderr } = captureStderr(() => buildPluginAssets({ pluginDir, verbose: false }));
 
   assert.equal(manifest.pluginId, "builder");
   assert.equal(fs.existsSync(path.join(pluginDir, "bin", "plugin.js")), true);
@@ -119,6 +135,42 @@ test("buildPluginAssets runs build:plugin and validates output", () => {
     fs.readFileSync(path.join(pluginDir, "bin", "openvcs-plugin.js"), "utf8"),
     /bootstrapPluginModule/
   );
+  assert.match(stderr, /openvcs build: reading plugin manifest/);
+  assert.match(stderr, /openvcs build: running build:plugin/);
+  assert.match(stderr, /openvcs build: generating bootstrap openvcs-plugin.js/);
+  assert.match(stderr, /openvcs build: validating bootstrap openvcs-plugin.js/);
+  assert.match(stderr, /openvcs build: build complete for builder/);
+  cleanupTempDir(root);
+});
+
+test("buildPluginAssets verbose mode adds detailed progress output", () => {
+  const root = makeTempDir("openvcs-sdk-test");
+  const pluginDir = path.join(root, "plugin");
+
+  writeJson(path.join(pluginDir, "package.json"), {
+    name: "verbose-builder",
+    private: true,
+    type: "module",
+    openvcs: {
+      id: "verbose-builder",
+      module: { exec: "openvcs-plugin.mjs" },
+    },
+    scripts: {
+      "build:plugin": "node ./scripts/build-plugin.cjs",
+    },
+  });
+  writeText(
+    path.join(pluginDir, "scripts", "build-plugin.cjs"),
+    "const fs = require('node:fs');\nconst path = require('node:path');\nconst out = path.join(process.cwd(), 'bin', 'plugin.js');\nfs.mkdirSync(path.dirname(out), { recursive: true });\nfs.writeFileSync(out, 'export {};\\n', 'utf8');\n"
+  );
+
+  const { result: manifest, stderr } = captureStderr(() => buildPluginAssets({ pluginDir, verbose: true }));
+
+  assert.equal(manifest.pluginId, "verbose-builder");
+  assert.match(stderr, /openvcs build: reading manifest at .*package\.json/);
+  assert.match(stderr, /openvcs build: manifest loaded for verbose-builder \(module\.exec: openvcs-plugin\.mjs\)/);
+  assert.match(stderr, /Running command in .*: .* run build:plugin/);
+  assert.match(stderr, /openvcs build: writing bootstrap .*openvcs-plugin\.mjs -> .*plugin\.js \(esm\)/);
   cleanupTempDir(root);
 });
 

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

@@ -53,6 +53,34 @@ class DerivedBranchDelegates extends SharedBranchDelegates {
   }
 }
 
+class BinaryAwareDelegates extends VcsDelegateBase {
+  getStatusPayload() {
+    return {
+      files: [
+        {
+          path: 'img.png',
+          old_path: null,
+          status: 'M',
+          staged: false,
+          resolved_conflict: false,
+          hunks: [],
+          binary: true,
+        },
+      ],
+      ahead: 0,
+      behind: 0,
+      branch_on_remote: false,
+    };
+  }
+
+  diffFile() {
+    return {
+      lines: ['Binary files a/img.png and b/img.png differ'],
+      binary: true,
+    };
+  }
+}
+
 test('VcsDelegateBase maps overridden camelCase methods to rpc delegates', async () => {
   const delegate = new ExampleVcsDelegates({ prefix: 'commit', calls: [] });
   const delegates = delegate.toDelegates();
@@ -110,6 +138,44 @@ test('VcsDelegateBase keeps inherited overrides when building delegates', async
   );
 });
 
+test('VcsDelegateBase preserves binary metadata in status and diff payloads', async () => {
+  const delegates = new BinaryAwareDelegates({}).toDelegates();
+
+  assert.deepEqual(
+    await delegates['vcs.get_status_payload'](
+      { session_id: 'session-4' },
+      { host: {}, method: 'vcs.get_status_payload', requestId: 11 },
+    ),
+    {
+      files: [
+        {
+          path: 'img.png',
+          old_path: null,
+          status: 'M',
+          staged: false,
+          resolved_conflict: false,
+          hunks: [],
+          binary: true,
+        },
+      ],
+      ahead: 0,
+      behind: 0,
+      branch_on_remote: false,
+    },
+  );
+
+  assert.deepEqual(
+    await delegates['vcs.diff_file'](
+      { session_id: 'session-4', path: 'img.png' },
+      { host: {}, method: 'vcs.diff_file', requestId: 12 },
+    ),
+    {
+      lines: ['Binary files a/img.png and b/img.png differ'],
+      binary: true,
+    },
+  );
+});
+
 test('VcsDelegateBase returns a fresh delegate map on each call', async () => {
   const delegate = new ExampleVcsDelegates({ prefix: 'repeat', calls: [] });
   const firstDelegates = delegate.toDelegates();