@openvcs/git-plugin 0.1.0 → 0.2.0-edge.20260426.39

package/ARCHITECTURE.md

@@ -23,12 +23,20 @@ through `@openvcs/sdk/runtime` delegates and exposes a single VCS backend id:
   exact `vcs.*` JSON-RPC method names consumed by the runtime.
 - Status reads use `git status --porcelain=1 --branch -z -uall` so file paths are
   NUL-delimited and not C-quoted.
+- After porcelain parsing, the plugin cross-references `.gitmodules` paths so
+  tracked submodule entries are surfaced with a dedicated submodule status marker
+  for the client UI.
 - For rename and copy records, the porcelain format includes two NUL-terminated
   paths: the original/source path first, then the new/destination path. The
   plugin assigns `path` to the new path and `old_path` to the original path.
 - Network commands (`fetch`, `push`, `pull`) omit optional arguments (remote,
   refspec, branch) when not provided, allowing Git to use its defaults instead
   of receiving empty string arguments.
+- Clone uses `git clone --recurse-submodules` so repositories arrive with
+  submodules initialized by default.
+- The Repository menu submodule toolkit keeps pinned `git submodule update`
+  behavior separate from explicit `--remote` updates that follow the configured
+  branch in `.gitmodules`.
 
 ## State
 

package/README.md

@@ -9,6 +9,9 @@ This directory contains the System Git VCS backend plugin used by OpenVCS.
 - The plugin can add top-level app menus and items through `@openvcs/sdk/runtime` helpers.
 - The plugin can open generic plugin-owned modals with the SDK `ModalBuilder` helper.
 - The Repository menu includes Git-only submodule management tooling.
+- In the desktop client, the `Submodules` entry appears in `Repository` after a Git repository is open and the Git plugin runtime is active.
+- Repository clone operations recurse into submodules by default.
+- Repository status views tag tracked submodule paths distinctly so the client can render them as submodules.
 - Git operations are executed through the local `git` CLI.
 - The runtime uses a trust model (no per-capability permission prompts).
 
@@ -18,7 +21,7 @@ This directory contains the System Git VCS backend plugin used by OpenVCS.
 npm install
 ```
 
-- The SDK dependency is pinned to the `^0.2` range so it tracks the latest `0.2.x` releases.
+- The SDK dependency tracks the `edge` tag so it always follows the latest SDK commit.
 
 ## Validate
 
@@ -41,6 +44,12 @@ npm run build
 npm test
 ```
 
+Submodule workflow highlights:
+
+- `clone_repo` uses `git clone --recurse-submodules`.
+- Repository > Submodules supports add, sync, remove, pinned updates, and explicit remote-tracking updates.
+- `Update Remote` follows the branch configured for each submodule in `.gitmodules`.
+
 ## Pack For Config Use
 
 ```bash
@@ -56,11 +65,13 @@ The npm package can be consumed from prerelease channels published by CI:
 
 - `latest`: stable releases
 - `beta`: builds from the `Beta` branch
+- `edge`: working builds from `Dev` push commits
 - `nightly`: scheduled builds from `Dev` when there are changes since the last nightly
 
 Examples:
 
 ```bash
+npm install @openvcs/git-plugin@edge
 npm install @openvcs/git-plugin@beta
 npm install @openvcs/git-plugin@nightly
 ```

package/bin/git.js

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { pluginError } from '@openvcs/sdk/runtime';
-import { asString, buildFetchArgs, buildPullFfOnlyArgs, buildPushArgs, parseCommits, parseStatusOutput, } from './plugin-helpers.js';
+import { applySubmoduleStatusHints, asString, buildFetchArgs, buildPullFfOnlyArgs, buildPushArgs, buildSubmoduleUpdateArgs, parseCommits, parseStatusOutput, } from './plugin-helpers.js';
 export class GitCommand {
     cwd;
     constructor(cwd) {
@@ -60,7 +60,7 @@ export class GitCommand {
     }
     status() {
         const result = this.run(['status', '--porcelain=1', '--branch', '-z', '-uall']);
-        const parsed = parseStatusOutput(result.stdout);
+        const parsed = applySubmoduleStatusHints(parseStatusOutput(result.stdout), this.listSubmodulePaths());
         return { ...parsed, exitCode: result.status };
     }
     currentBranch() {
@@ -163,26 +163,41 @@ export class GitCommand {
         const args = buildPullFfOnlyArgs(options);
         return this.runChecked(args, 'git-pull-failed');
     }
-    commit(message) {
-        return this.runChecked(['commit', '-m', message], 'git-commit-failed');
+    /** Returns the current HEAD commit id. */
+    currentHead() {
+        return this.runChecked(['rev-parse', 'HEAD'], 'git-head-failed').stdout.trim();
     }
-    commitIndex(message, name, email, paths) {
-        const args = ['commit'];
-        if (paths && paths.length > 0) {
-            args.push('--', ...paths);
-        }
-        else {
-            args.push('-a');
-        }
+    /** Creates a commit, optionally limited to the provided paths. */
+    commit(message, name, email, paths) {
+        const execArgs = [
+            ...(name ? ['-c', `user.name=${name}`] : []),
+            ...(email ? ['-c', `user.email=${email}`] : []),
+            'commit',
+            '-m',
+            message,
+            ...(paths && paths.length > 0 ? ['--', ...paths] : []),
+        ];
+        return this.runChecked(execArgs, 'git-commit-failed');
+    }
+    /** Creates a commit from the current index only. */
+    commitIndex(message, name, email) {
         const commitMessage = message || 'Stage changes';
         const execArgs = [
             ...(name ? ['-c', `user.name=${name}`] : []),
             ...(email ? ['-c', `user.email=${email}`] : []),
-            ...args,
-            '-m', commitMessage,
+            'commit',
+            '-m',
+            commitMessage,
         ];
         return this.runChecked(execArgs, 'git-commit-failed');
     }
+    /** Stages the provided repository-relative paths into the index. */
+    stagePaths(paths) {
+        if (paths.length === 0) {
+            return;
+        }
+        this.runChecked(['add', '-A', '--', ...paths], 'git-stage-paths-failed');
+    }
     listCommits(options = {}) {
         const args = ['log', '--all'];
         if (options.topo_order) {
@@ -206,7 +221,7 @@ export class GitCommand {
         if (options.until_utc) {
             args.push(`--until=${options.until_utc}`);
         }
-        args.push('--pretty=format:%H%f%x00%aN%x00%aI%x00%P%x1e');
+        args.push('--pretty=format:%H%x00%s%x00%aN%x00%aI%x00%P%x1e');
         if (options.branch) {
             args.push(options.branch);
         }
@@ -217,9 +232,10 @@ export class GitCommand {
         const commits = parseCommits(result.stdout);
         return { commits, exitCode: result.status };
     }
-    listSubmodules() {
+    /** Reads `.gitmodules` entries indexed by submodule name and path. */
+    readSubmoduleConfig() {
         const configResult = this.run(['config', '-f', '.gitmodules', '--null', '--list']);
-        const configByName = new Map();
+        const byName = new Map();
         if (configResult.status === 0) {
             for (const entry of configResult.stdout.split('\0')) {
                 const trimmed = entry.trim();
@@ -234,22 +250,30 @@ export class GitCommand {
                 if (!match)
                     continue;
                 const [, name, field] = match;
-                const target = configByName.get(name) || { name };
+                const target = byName.get(name) || { name };
                 if (field === 'path')
                     target.path = value;
                 if (field === 'url')
                     target.url = value;
                 if (field === 'branch')
                     target.branch = value;
-                configByName.set(name, target);
+                byName.set(name, target);
             }
         }
-        const configByPath = new Map();
-        for (const entry of configByName.values()) {
+        const byPath = new Map();
+        for (const entry of byName.values()) {
             if (entry.path) {
-                configByPath.set(entry.path, entry);
+                byPath.set(entry.path, entry);
             }
         }
+        return { byName, byPath };
+    }
+    /** Returns known submodule paths from `.gitmodules`. */
+    listSubmodulePaths() {
+        return new Set(this.readSubmoduleConfig().byPath.keys());
+    }
+    listSubmodules() {
+        const { byPath: configByPath } = this.readSubmoduleConfig();
         const statusResult = this.run(['submodule', 'status', '--recursive']);
         if (statusResult.status !== 0) {
             return [];
@@ -295,10 +319,18 @@ export class GitCommand {
         return this.runChecked(args, 'git-submodule-add-failed');
     }
     updateSubmodule(path) {
-        return this.runChecked(['submodule', 'update', '--init', '--recursive', '--', path], 'git-submodule-update-failed');
+        return this.runChecked(buildSubmoduleUpdateArgs({ path }), 'git-submodule-update-failed');
     }
     updateAllSubmodules() {
-        return this.runChecked(['submodule', 'update', '--init', '--recursive'], 'git-submodule-update-failed');
+        return this.runChecked(buildSubmoduleUpdateArgs({}), 'git-submodule-update-failed');
+    }
+    /** Updates one submodule from its configured branch recursively. */
+    updateSubmoduleRemote(path) {
+        return this.runChecked(buildSubmoduleUpdateArgs({ path, remote: true }), 'git-submodule-update-remote-failed');
+    }
+    /** Updates all submodules from their configured branches recursively. */
+    updateAllSubmodulesRemote() {
+        return this.runChecked(buildSubmoduleUpdateArgs({ remote: true }), 'git-submodule-update-remote-failed');
     }
     syncSubmodule(path) {
         return this.runChecked(['submodule', 'sync', '--recursive', '--', path], 'git-submodule-sync-failed');
@@ -354,8 +386,11 @@ export class GitCommand {
     hashObject(content) {
         return this.run(['hash-object', '-w', '--stdin'], { stdin: content }).stdout.trim();
     }
+    /** Stages a textual patch into the index without requiring worktree/index parity. */
     stagePatch(patch) {
-        this.runChecked(['apply', '--3way', '--index'], 'git-stage-patch-failed', { stdin: patch });
+        this.runChecked(['apply', '--cached', '--unidiff-zero'], 'git-stage-patch-failed', {
+            stdin: patch,
+        });
     }
     applyReversePatch(patch) {
         this.runChecked(['apply', '-R', patch], 'git-apply-reverse-failed');
@@ -366,9 +401,10 @@ export class GitCommand {
     resetSoftTo(ref) {
         this.runChecked(['reset', '--soft', ref], 'git-reset-soft-failed');
     }
+    /** Reads the effective Git commit identity from config. */
     getIdentity() {
-        const nameResult = this.run(['config', '--local', 'user.name']);
-        const emailResult = this.run(['config', '--local', 'user.email']);
+        const nameResult = this.run(['config', '--get', 'user.name']);
+        const emailResult = this.run(['config', '--get', 'user.email']);
         if (nameResult.status !== 0 || emailResult.status !== 0) {
             return null;
         }
@@ -377,6 +413,7 @@ export class GitCommand {
             email: emailResult.stdout.trim(),
         };
     }
+    /** Stores repository-local commit identity in Git config. */
     setIdentityLocal(name, email) {
         this.runChecked(['config', '--local', 'user.name', name], 'git-identity-set-failed');
         this.runChecked(['config', '--local', 'user.email', email], 'git-identity-set-failed');

package/bin/plugin-helpers.js

@@ -52,6 +52,13 @@ export function buildPushArgs(params) {
     pushOptionalArg(args, params.refspec);
     return args;
 }
+/** Builds `git clone` arguments with recursive submodule initialization enabled. */
+export function buildCloneArgs(params) {
+    const args = ['clone', '--recurse-submodules'];
+    pushOptionalArg(args, params.url);
+    pushOptionalArg(args, params.dest);
+    return args;
+}
 /** Builds `git pull --ff-only` arguments while omitting empty optional values. */
 export function buildPullFfOnlyArgs(params) {
     const args = ['pull', '--ff-only'];
@@ -59,6 +66,18 @@ export function buildPullFfOnlyArgs(params) {
     pushOptionalArg(args, params.branch);
     return args;
 }
+/** Builds `git submodule update` arguments for pinned or remote-tracking updates. */
+export function buildSubmoduleUpdateArgs(params) {
+    const args = ['submodule', 'update', '--init', '--recursive'];
+    if (params.remote === true) {
+        args.push('--remote');
+    }
+    const path = asTrimmedString(params.path);
+    if (path) {
+        args.push('--', path);
+    }
+    return args;
+}
 /** Parses `git status --porcelain=1 --branch -z -uall` output into OpenVCS payloads. */
 export function parseStatusOutput(output) {
     const records = output.split('\0').filter(Boolean);
@@ -130,6 +149,31 @@ export function parseStatusOutput(output) {
         },
     };
 }
+/** Applies submodule-specific status labels to known submodule paths. */
+export function applySubmoduleStatusHints(parsed, submodulePaths) {
+    const knownPaths = new Set(Array.from(submodulePaths)
+        .map((entry) => asTrimmedString(entry))
+        .filter(Boolean));
+    if (knownPaths.size === 0) {
+        return parsed;
+    }
+    return {
+        ...parsed,
+        payload: {
+            ...parsed.payload,
+            files: parsed.payload.files.map((file) => {
+                const path = asTrimmedString(file.path);
+                if (!knownPaths.has(path)) {
+                    return file;
+                }
+                return {
+                    ...file,
+                    status: 'S',
+                };
+            }),
+        },
+    };
+}
 /** Parses `git log` output into commit entries expected by the host. */
 export function parseCommits(raw) {
     const records = raw

package/bin/plugin-request-handler.js

@@ -1,8 +1,67 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 import { VcsDelegateBase, pluginError, } from '@openvcs/sdk/runtime';
-import { asNumber, asRecord, asString, asStringArray, asTrimmedString, } from './plugin-helpers.js';
+import { asNumber, asRecord, asString, asStringArray, asTrimmedString, buildCloneArgs, parseStatusOutput, } from './plugin-helpers.js';
 import { GitCommand } from './git.js';
+/** Returns an optional boolean only when the input is already a boolean. */
+function asOptionalBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+/** Reduces a file status string to the primary status code needed for discard routing. */
+function getPrimaryDiscardStatus(status) {
+    const normalized = asTrimmedString(status);
+    if (!normalized) {
+        return 'M';
+    }
+    for (const candidate of ['?', 'R', 'C', 'A', 'D', 'U', 'T', 'S', 'M']) {
+        if (normalized.includes(candidate)) {
+            return candidate;
+        }
+    }
+    return normalized[0] ?? 'M';
+}
+/** Builds a discard plan that handles tracked, added, copied, and renamed paths. */
+export function planDiscardPaths(statusOutput) {
+    const restore = new Set();
+    const unstageThenRemove = new Set();
+    const clean = new Set();
+    const parsed = parseStatusOutput(statusOutput);
+    for (const file of parsed.payload.files) {
+        const path = asTrimmedString(file.path);
+        const oldPath = asTrimmedString(file.old_path);
+        const primaryStatus = getPrimaryDiscardStatus(file.status);
+        if (!path) {
+            continue;
+        }
+        if (primaryStatus === '?') {
+            clean.add(path);
+            continue;
+        }
+        if (primaryStatus === 'R') {
+            if (oldPath) {
+                restore.add(oldPath);
+            }
+            if (file.staged) {
+                unstageThenRemove.add(path);
+            }
+            clean.add(path);
+            continue;
+        }
+        if (primaryStatus === 'C' || primaryStatus === 'A') {
+            if (file.staged) {
+                unstageThenRemove.add(path);
+            }
+            clean.add(path);
+            continue;
+        }
+        restore.add(path);
+    }
+    return {
+        restore: Array.from(restore),
+        unstageThenRemove: Array.from(unstageThenRemove),
+        clean: Array.from(clean),
+    };
+}
 /** Implements the Git-backed `vcs.*` delegate surface for the SDK runtime. */
 export class GitVcsDelegates extends VcsDelegateBase {
     /** Returns the required repository worktree path for a session id. */
@@ -45,7 +104,7 @@ export class GitVcsDelegates extends VcsDelegateBase {
             throw pluginError('vcs-clone-invalid-args', 'url and dest are required');
         }
         const git = this.deps.createGitCommand(process.cwd());
-        const output = git.runChecked(['clone', url, destination], 'vcs-clone-failed');
+        const output = git.runChecked(buildCloneArgs({ url, dest: destination }), 'vcs-clone-failed');
         const lines = `${output.stdout}\n${output.stderr}`
             .split(/\r?\n/g)
             .map((line) => line.trim())
@@ -159,15 +218,13 @@ export class GitVcsDelegates extends VcsDelegateBase {
     }
     commit(params, _context) {
         const git = this.requireGit(params.session_id);
-        const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
-        git.commit(asTrimmedString(params.message));
-        return result.stdout.trim();
+        git.commit(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email), asStringArray(params.paths));
+        return git.currentHead();
     }
     commitIndex(params, _context) {
         const git = this.requireGit(params.session_id);
-        const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
-        git.commitIndex(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email), asStringArray(params.paths));
-        return result.stdout.trim();
+        git.commitIndex(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email));
+        return git.currentHead();
     }
     getStatusSummary(params, _context) {
         const git = this.requireGit(params.session_id);
@@ -184,8 +241,8 @@ export class GitVcsDelegates extends VcsDelegateBase {
             branch: asTrimmedString(query.rev) || undefined,
             skip: asNumber(query.skip, 0) || undefined,
             limit: asNumber(query.limit, 0),
-            topo_order: query.topo_order ?? undefined,
-            include_merges: query.include_merges ?? undefined,
+            topo_order: asOptionalBoolean(query.topo_order),
+            include_merges: asOptionalBoolean(query.include_merges),
             author_contains: asTrimmedString(query.author_contains) || undefined,
             since_utc: asTrimmedString(query.since_utc) || undefined,
             until_utc: asTrimmedString(query.until_utc) || undefined,
@@ -225,13 +282,42 @@ export class GitVcsDelegates extends VcsDelegateBase {
         git.stagePatch(asString(params.patch));
         return null;
     }
+    stagePaths(params, _context) {
+        const git = this.requireGit(params.session_id);
+        git.stagePaths(asStringArray(params.paths));
+        return null;
+    }
     discardPaths(params, _context) {
         const git = this.requireGit(params.session_id);
         const paths = asStringArray(params.paths);
         if (paths.length === 0) {
             return null;
         }
-        git.runChecked(['checkout', '--', ...paths], 'git-discard-paths-failed');
+        const status = git.runChecked(['status', '--porcelain=1', '-z', '-uall', '--', ...paths], 'git-discard-paths-failed');
+        const discardPlan = planDiscardPaths(status.stdout);
+        let failure;
+        if (discardPlan.unstageThenRemove.length > 0) {
+            try {
+                git.runChecked(['rm', '-f', '--cached', '--', ...discardPlan.unstageThenRemove], 'git-discard-paths-failed');
+            }
+            catch (error) {
+                failure = error;
+            }
+        }
+        if (!failure && discardPlan.restore.length > 0) {
+            try {
+                git.runChecked(['restore', '--source=HEAD', '--staged', '--worktree', '--', ...discardPlan.restore], 'git-discard-paths-failed');
+            }
+            catch (error) {
+                failure = error;
+            }
+        }
+        if (!failure && discardPlan.clean.length > 0) {
+            git.runChecked(['clean', '-f', '--', ...discardPlan.clean], 'git-discard-paths-failed');
+        }
+        if (failure) {
+            throw failure;
+        }
         return null;
     }
     applyReversePatch(params, _context) {

package/bin/plugin.js

@@ -38,7 +38,7 @@ export function OnPluginStart() {
     }
     const delegates = new GitVcsDelegates(createGitRuntimeDependencies());
     PluginDefinition.vcs = delegates.toDelegates();
-    const repoMenu = getOrCreateMenu('repository', 'Repository');
+    const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
     if (repoMenu) {
         repoMenu.addItem({ label: 'Edit .gitignore', action: 'repo-edit-gitignore' });
         repoMenu.addItem({ label: 'Edit .gitattributes', action: 'repo-edit-gitattributes' });