@openvcs/git-plugin 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# Git Plugin
+
+This directory contains the System Git VCS backend plugin used by OpenVCS.
+
+## Runtime model
+
+- The plugin runs as a long-lived Node.js process.
+- The plugin implements the JSON-RPC contract used by the backend runtime (`plugin.*` and `vcs.*`) through the shared SDK runtime delegates.
+- 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.
+- Git operations are executed through the local `git` CLI.
+- The runtime uses a trust model (no per-capability permission prompts).
+
+## Install
+
+```bash
+npm install
+```
+
+- The SDK dependency is pinned to the `^0.2` range so it tracks the latest `0.2.x` releases.
+
+## Validate
+
+```bash
+npm run lint
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+- TypeScript sources live in `src/`.
+- `npm run build` runs `openvcs build`, which invokes `build:plugin` and writes the runtime into `bin/`.
+
+## Test
+
+```bash
+npm test
+```
+
+## Pack For Config Use
+
+```bash
+npm pack
+```
+
+- `npm pack` uses the package `files` list and `prepack` hook.
+- OpenVCS resolves published packages and local path plugins through npm package semantics.
+
+## Release Channels
+
+The npm package can be consumed from prerelease channels published by CI:
+
+- `latest`: stable releases
+- `beta`: builds from the `Beta` branch
+- `nightly`: scheduled builds from `Dev` when there are changes since the last nightly
+
+Examples:
+
+```bash
+npm install @openvcs/git-plugin@beta
+npm install @openvcs/git-plugin@nightly
+```

package/bin/git.js

@@ -0,0 +1,446 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+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';
+export class GitCommand {
+    cwd;
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    run(args, options = {}) {
+        const result = spawnSync('git', args, {
+            cwd: this.cwd,
+            input: typeof options.stdin === 'string' ? options.stdin : undefined,
+            encoding: 'utf8',
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        if (result.status === null) {
+            const signal = result.signal ?? 'unknown';
+            console.warn(`git process killed/crashed (signal: ${signal}) in ${this.cwd}: ${args.join(' ')}`);
+            return {
+                status: -2,
+                stdout: asString(result.stdout),
+                stderr: asString(result.stderr) || `Process terminated by signal: ${signal}`,
+            };
+        }
+        return {
+            status: result.status,
+            stdout: asString(result.stdout),
+            stderr: asString(result.stderr),
+        };
+    }
+    runChecked(args, errorCode, options = {}) {
+        const output = this.run(args, options);
+        if (output.status !== 0) {
+            const exitInfo = output.status === -2 ? ` (signal: ${output.stderr})` : ` (exit code: ${output.status})`;
+            const message = output.stderr.trim() ||
+                output.stdout.trim() ||
+                `git ${args.join(' ')}${exitInfo}`;
+            throw pluginError(errorCode, message);
+        }
+        return output;
+    }
+    version() {
+        const result = this.run(['--version']);
+        const versionMatch = result.stdout.match(/git version (\d+)\.(\d+)/);
+        if (!versionMatch) {
+            throw new Error(`Unable to parse Git version: ${result.stdout.trim()}`);
+        }
+        const major = parseInt(versionMatch[1], 10);
+        const minor = parseInt(versionMatch[2], 10);
+        return {
+            result,
+            version: versionMatch[0],
+            major,
+            minor,
+        };
+    }
+    status() {
+        const result = this.run(['status', '--porcelain=1', '--branch', '-z', '-uall']);
+        const parsed = parseStatusOutput(result.stdout);
+        return { ...parsed, exitCode: result.status };
+    }
+    currentBranch() {
+        const result = this.runChecked(['rev-parse', '--abbrev-ref', 'HEAD'], 'git-branch-failed');
+        return result.stdout.trim();
+    }
+    listBranches() {
+        const result = this.run(['branch', '-a', '--format=%(refname:short)%(if)%(HEAD)%(then)*%(end)']);
+        const current = this.currentBranch();
+        const branches = [];
+        for (const line of result.stdout.split('\n').filter(Boolean)) {
+            const isCurrent = line.endsWith('*');
+            const baseLine = isCurrent ? line.slice(0, -1) : line;
+            const name = baseLine.trim();
+            if (name) {
+                branches.push({ name, current: name === current || (isCurrent && name === current) });
+            }
+        }
+        return { current, branches };
+    }
+    listLocalBranches() {
+        const result = this.run(['branch', '--format=%(refname:short)%(if)%(HEAD)%(then)*%(end)']);
+        const current = this.currentBranch();
+        const branches = [];
+        for (const line of result.stdout.split('\n').filter(Boolean)) {
+            const trimmed = line.replaceAll('*', '').trim();
+            if (trimmed) {
+                branches.push({ name: trimmed, current: trimmed === current });
+            }
+        }
+        return { current, branches };
+    }
+    createBranch(name) {
+        this.runChecked(['branch', name], 'git-branch-create-failed');
+    }
+    checkoutBranch(name) {
+        this.runChecked(['checkout', name], 'git-checkout-failed');
+    }
+    deleteBranch(name) {
+        this.runChecked(['branch', '-d', name], 'git-branch-delete-failed');
+    }
+    renameBranch(oldName, newName) {
+        this.runChecked(['branch', '-m', oldName, newName], 'git-branch-rename-failed');
+    }
+    getBranchUpstream(branchName) {
+        const result = this.run(['rev-parse', '--abbrev-ref', `${branchName}@{upstream}`]);
+        return result.status === 0 ? result.stdout.trim() : null;
+    }
+    setBranchUpstream(branchName, upstream) {
+        this.runChecked(['branch', '--set-upstream-to', upstream, branchName], 'git-branch-upstream-failed');
+    }
+    ensureRemote(name, url) {
+        const probe = this.run(['remote', 'get-url', name]);
+        if (probe.status === 0) {
+            if (probe.stdout.trim() !== url) {
+                this.runChecked(['remote', 'set-url', name, url], 'git-remote-set-url-failed');
+            }
+        }
+        else {
+            this.runChecked(['remote', 'add', name, url], 'git-remote-add-failed');
+        }
+    }
+    listRemotes() {
+        const result = this.runChecked(['remote', '-v'], 'git-remote-list-failed');
+        const remotes = [];
+        const remoteMap = new Map();
+        for (const line of result.stdout.split('\n').filter(Boolean)) {
+            const match = line.match(/^(\S+)\s+(\S+)\s+\((\w+)\)$/);
+            if (match) {
+                const [, name, url, type] = match;
+                if (!remoteMap.has(name)) {
+                    remoteMap.set(name, { fetch: '', push: '' });
+                }
+                const entry = remoteMap.get(name);
+                if (type === 'fetch') {
+                    entry.fetch = url;
+                }
+                else if (type === 'push') {
+                    entry.push = url;
+                }
+            }
+        }
+        remoteMap.forEach((value, key) => {
+            remotes.push({ name: key, ...value });
+        });
+        return { remotes };
+    }
+    removeRemote(name) {
+        this.runChecked(['remote', 'remove', name], 'git-remote-remove-failed');
+    }
+    fetch(options = {}) {
+        const args = buildFetchArgs(options);
+        return this.runChecked(args, 'git-fetch-failed');
+    }
+    push(options = {}) {
+        const args = buildPushArgs(options);
+        return this.runChecked(args, 'git-push-failed');
+    }
+    pull(options = {}) {
+        const args = buildPullFfOnlyArgs(options);
+        return this.runChecked(args, 'git-pull-failed');
+    }
+    commit(message) {
+        return this.runChecked(['commit', '-m', message], 'git-commit-failed');
+    }
+    commitIndex(message, name, email, paths) {
+        const args = ['commit'];
+        if (paths && paths.length > 0) {
+            args.push('--', ...paths);
+        }
+        else {
+            args.push('-a');
+        }
+        const commitMessage = message || 'Stage changes';
+        const execArgs = [
+            ...(name ? ['-c', `user.name=${name}`] : []),
+            ...(email ? ['-c', `user.email=${email}`] : []),
+            ...args,
+            '-m', commitMessage,
+        ];
+        return this.runChecked(execArgs, 'git-commit-failed');
+    }
+    listCommits(options = {}) {
+        const args = ['log', '--all'];
+        if (options.topo_order) {
+            args.push('--topo-order');
+        }
+        if (options.limit !== undefined) {
+            args.push(`-${options.limit}`);
+        }
+        if (options.skip !== undefined) {
+            args.push(`--skip=${options.skip}`);
+        }
+        if (options.include_merges === false) {
+            args.push('--no-merges');
+        }
+        if (options.author_contains) {
+            args.push(`--author=${options.author_contains}`);
+        }
+        if (options.since_utc) {
+            args.push(`--since=${options.since_utc}`);
+        }
+        if (options.until_utc) {
+            args.push(`--until=${options.until_utc}`);
+        }
+        args.push('--pretty=format:%H%f%x00%aN%x00%aI%x00%P%x1e');
+        if (options.branch) {
+            args.push(options.branch);
+        }
+        if (options.path) {
+            args.push('--', options.path);
+        }
+        const result = this.run(args);
+        const commits = parseCommits(result.stdout);
+        return { commits, exitCode: result.status };
+    }
+    listSubmodules() {
+        const configResult = this.run(['config', '-f', '.gitmodules', '--null', '--list']);
+        const configByName = new Map();
+        if (configResult.status === 0) {
+            for (const entry of configResult.stdout.split('\0')) {
+                const trimmed = entry.trim();
+                if (!trimmed)
+                    continue;
+                const splitAt = trimmed.indexOf('\n');
+                if (splitAt < 0)
+                    continue;
+                const key = trimmed.slice(0, splitAt).trim();
+                const value = trimmed.slice(splitAt + 1);
+                const match = key.match(/^submodule\.(.+)\.(path|url|branch)$/);
+                if (!match)
+                    continue;
+                const [, name, field] = match;
+                const target = configByName.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);
+            }
+        }
+        const configByPath = new Map();
+        for (const entry of configByName.values()) {
+            if (entry.path) {
+                configByPath.set(entry.path, entry);
+            }
+        }
+        const statusResult = this.run(['submodule', 'status', '--recursive']);
+        if (statusResult.status !== 0) {
+            return [];
+        }
+        const stateFor = (marker) => {
+            if (marker === '-')
+                return 'uninitialized';
+            if (marker === '+')
+                return 'dirty';
+            if (marker === 'U')
+                return 'conflicted';
+            return 'clean';
+        };
+        const entries = [];
+        for (const rawLine of statusResult.stdout.split(/\r?\n/g)) {
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            const marker = line[0] || ' ';
+            const rest = line.slice(1).trim();
+            const [commit = '', path = ''] = rest.split(/\s+/);
+            if (!path)
+                continue;
+            const config = configByPath.get(path);
+            entries.push({
+                path,
+                name: config?.name || path.split('/').filter(Boolean).at(-1) || path,
+                url: config?.url,
+                branch: config?.branch,
+                commit,
+                state: stateFor(marker),
+            });
+        }
+        return entries.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    addSubmodule(url, path, name, branch) {
+        const args = ['submodule', 'add'];
+        if (name)
+            args.push('--name', name);
+        if (branch)
+            args.push('--branch', branch);
+        args.push(url, path);
+        return this.runChecked(args, 'git-submodule-add-failed');
+    }
+    updateSubmodule(path) {
+        return this.runChecked(['submodule', 'update', '--init', '--recursive', '--', path], 'git-submodule-update-failed');
+    }
+    updateAllSubmodules() {
+        return this.runChecked(['submodule', 'update', '--init', '--recursive'], 'git-submodule-update-failed');
+    }
+    syncSubmodule(path) {
+        return this.runChecked(['submodule', 'sync', '--recursive', '--', path], 'git-submodule-sync-failed');
+    }
+    syncAllSubmodules() {
+        return this.runChecked(['submodule', 'sync', '--recursive'], 'git-submodule-sync-failed');
+    }
+    removeSubmodule(path) {
+        this.runChecked(['submodule', 'deinit', '-f', '--', path], 'git-submodule-remove-failed');
+        this.runChecked(['rm', '-f', '--', path], 'git-submodule-remove-failed');
+        const modulesPath = join(this.cwd, '.git', 'modules', path);
+        try {
+            rmSync(modulesPath, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort cleanup.
+        }
+    }
+    diffFile(path) {
+        return this.runChecked(['diff', '--no-ext-diff', '--', path], 'git-diff-failed').stdout;
+    }
+    diffCommit(commit) {
+        return this.runChecked(['diff', `${commit}^`, commit], 'git-diff-failed').stdout;
+    }
+    getConflictDetails(path) {
+        const ours = this.run(['show', `:2:${path}`]);
+        const theirs = this.run(['show', `:3:${path}`]);
+        const base = this.run(['show', `:1:${path}`]);
+        if (ours.status !== 0 || theirs.status !== 0) {
+            return { path, ours: null, theirs: null, base: null, binary: false, lfs_pointer: false };
+        }
+        const oursContent = ours.stdout;
+        const lfs_pointer = ours.stdout.includes('version https://git-lfs.github.com/spec/v1') ||
+            theirs.stdout.includes('version https://git-lfs.github.com/spec/v1');
+        const binary = !lfs_pointer && (oursContent.startsWith('Binary\0') || oursContent.includes('\0'));
+        return {
+            path,
+            ours: ours.stdout,
+            theirs: theirs.stdout,
+            base: base.status === 0 ? base.stdout : null,
+            binary,
+            lfs_pointer,
+        };
+    }
+    checkoutConflictSide(path, side) {
+        const ref = side === 'ours' ? ':2' : ':3';
+        this.runChecked(['checkout', ref, '--', path], 'git-checkout-conflict-failed');
+    }
+    writeMergeResult(path, content) {
+        const args = ['update-index', '--add', '--cacheinfo', '100644', this.hashObject(content), path];
+        this.runChecked(args, 'git-write-merge-result-failed');
+    }
+    hashObject(content) {
+        return this.run(['hash-object', '-w', '--stdin'], { stdin: content }).stdout.trim();
+    }
+    stagePatch(patch) {
+        this.runChecked(['apply', '--3way', '--index'], 'git-stage-patch-failed', { stdin: patch });
+    }
+    applyReversePatch(patch) {
+        this.runChecked(['apply', '-R', patch], 'git-apply-reverse-failed');
+    }
+    hardResetHead(ref) {
+        this.runChecked(['reset', '--hard', ref ?? 'HEAD'], 'git-reset-hard-failed');
+    }
+    resetSoftTo(ref) {
+        this.runChecked(['reset', '--soft', ref], 'git-reset-soft-failed');
+    }
+    getIdentity() {
+        const nameResult = this.run(['config', '--local', 'user.name']);
+        const emailResult = this.run(['config', '--local', 'user.email']);
+        if (nameResult.status !== 0 || emailResult.status !== 0) {
+            return null;
+        }
+        return {
+            name: nameResult.stdout.trim(),
+            email: emailResult.stdout.trim(),
+        };
+    }
+    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');
+    }
+    mergeIntoCurrent(branch) {
+        this.runChecked(['merge', branch], 'git-merge-failed');
+    }
+    mergeAbort() {
+        this.runChecked(['merge', '--abort'], 'git-merge-abort-failed');
+    }
+    mergeContinue(message) {
+        const args = ['commit'];
+        if (message) {
+            args.push('-m', message);
+        }
+        this.runChecked(args, 'git-merge-continue-failed');
+    }
+    isMergeInProgress() {
+        const result = this.run(['rev-parse', '--verify', '-q', 'MERGE_HEAD']);
+        return result.status === 0;
+    }
+    listStashes() {
+        const result = this.runChecked(['stash', 'list', '--pretty=format:%gd%x1f%s%x1e'], 'git-stash-list-failed');
+        return result.stdout
+            .split('\u001e')
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            const [selector = '', msg = ''] = line.split('\u001f');
+            return { selector, msg, meta: '' };
+        });
+    }
+    stashPush(message, includeUntracked) {
+        const args = ['stash', 'push'];
+        if (includeUntracked) {
+            args.push('--include-untracked');
+        }
+        if (message) {
+            args.push('-m', message);
+        }
+        this.runChecked(args, 'git-stash-push-failed');
+        return this.runChecked(['stash', 'list', '-n', '1', '--pretty=format:%gd'], 'git-stash-push-failed').stdout.trim();
+    }
+    stashApply(selector) {
+        this.runChecked(['stash', 'apply', selector], 'git-stash-apply-failed');
+    }
+    stashPop(selector) {
+        this.runChecked(['stash', 'pop', selector], 'git-stash-pop-failed');
+    }
+    stashDrop(selector) {
+        this.runChecked(['stash', 'drop', selector], 'git-stash-drop-failed');
+    }
+    stashShow(selector) {
+        return this.runChecked(['stash', 'show', '-p', selector], 'git-stash-show-failed').stdout;
+    }
+    cherryPick(commit) {
+        this.runChecked(['cherry-pick', commit], 'git-cherry-pick-failed');
+    }
+    revertCommit(commit, noEdit) {
+        const args = ['revert'];
+        if (noEdit) {
+            args.push('--no-edit');
+        }
+        args.push(commit);
+        this.runChecked(args, 'git-revert-failed');
+    }
+}

package/bin/openvcs-git-plugin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { bootstrapPluginModule } from '@openvcs/sdk/runtime';
+
+await bootstrapPluginModule({
+  importPluginModule: async () => import('./plugin.js'),
+  modulePath: './plugin.js',
+});

package/bin/plugin-helpers.js

@@ -0,0 +1,149 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+/** Returns a plain object parameter map or an empty object for invalid input. */
+export function asRecord(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+/** Coerces any value into a string while preserving empty defaults. */
+export function asString(value) {
+    return typeof value === 'string' ? value : String(value ?? '');
+}
+/** Coerces any value into a trimmed string. */
+export function asTrimmedString(value) {
+    return asString(value).trim();
+}
+/** Coerces any value into a finite number or returns a fallback. */
+export function asNumber(value, fallback) {
+    const numericValue = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(numericValue) ? numericValue : fallback;
+}
+/** Coerces an unknown value into a filtered list of non-empty strings. */
+export function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry) => asString(entry)).filter(Boolean);
+}
+/** Adds a trimmed string argument when a value is present. */
+function pushOptionalArg(args, value) {
+    const candidate = asTrimmedString(value);
+    if (candidate) {
+        args.push(candidate);
+    }
+}
+/** Builds `git fetch` arguments while omitting empty optional values. */
+export function buildFetchArgs(params) {
+    const args = ['fetch'];
+    const options = asRecord(params.opts);
+    if (options.prune === true) {
+        args.push('--prune');
+    }
+    pushOptionalArg(args, params.remote);
+    pushOptionalArg(args, params.refspec);
+    return args;
+}
+/** Builds `git push` arguments while omitting empty optional values. */
+export function buildPushArgs(params) {
+    const args = ['push'];
+    pushOptionalArg(args, params.remote);
+    pushOptionalArg(args, params.refspec);
+    return args;
+}
+/** Builds `git pull --ff-only` arguments while omitting empty optional values. */
+export function buildPullFfOnlyArgs(params) {
+    const args = ['pull', '--ff-only'];
+    pushOptionalArg(args, params.remote);
+    pushOptionalArg(args, params.branch);
+    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);
+    let ahead = 0;
+    let behind = 0;
+    const files = [];
+    const summary = {
+        untracked: 0,
+        modified: 0,
+        staged: 0,
+        conflicted: 0,
+    };
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (record.startsWith('## ')) {
+            const aheadMatch = record.match(/ahead\s+(\d+)/);
+            const behindMatch = record.match(/behind\s+(\d+)/);
+            ahead = aheadMatch ? Number(aheadMatch[1]) : 0;
+            behind = behindMatch ? Number(behindMatch[1]) : 0;
+            continue;
+        }
+        if (record.length < 4) {
+            continue;
+        }
+        const x = record[0];
+        const y = record[1];
+        const payloadPath = record.slice(3);
+        const renamedOrCopied = x === 'R' || x === 'C' || y === 'R' || y === 'C';
+        let path = payloadPath;
+        let oldPath = null;
+        if (renamedOrCopied && index + 1 < records.length) {
+            path = records[index + 1];
+            oldPath = payloadPath;
+            index += 1;
+        }
+        const staged = x !== ' ' && x !== '?';
+        if (x === '?' || y === '?') {
+            summary.untracked += 1;
+        }
+        else if (x === 'U' ||
+            y === 'U' ||
+            (x === 'A' && y === 'A') ||
+            (x === 'D' && y === 'D')) {
+            summary.conflicted += 1;
+        }
+        else {
+            if (staged) {
+                summary.staged += 1;
+            }
+            if (y !== ' ') {
+                summary.modified += 1;
+            }
+        }
+        files.push({
+            path,
+            old_path: oldPath,
+            status: `${x}${y}`.trim() || 'M',
+            staged,
+            resolved_conflict: false,
+            hunks: [],
+        });
+    }
+    return {
+        summary,
+        payload: {
+            files,
+            ahead,
+            behind,
+        },
+    };
+}
+/** Parses `git log` output into commit entries expected by the host. */
+export function parseCommits(raw) {
+    const records = raw
+        .split('\u001e')
+        .map((record) => record.trim())
+        .filter(Boolean);
+    return records.map((record) => {
+        const [id, msg, author, meta, parent_oid = ''] = record.split('\u0000');
+        return {
+            id: asString(id),
+            msg: asString(msg),
+            author: asString(author),
+            meta: asString(meta),
+            parent_oid: parent_oid || undefined,
+        };
+    });
+}