@devframes/service-git 0.9.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,214 @@
+import { DevframeServiceDefinition } from "devframe/types";
+//#region src/types.d.ts
+type FileStatusCode = 'modified' | 'added' | 'deleted' | 'renamed' | 'copied' | 'type-changed' | 'unmerged' | 'unknown';
+interface StatusFileEntry {
+  path: string;
+  /** Previous path, present for renames and copies. */
+  from?: string;
+  status: FileStatusCode;
+}
+interface GitStatus {
+  /** `false` when the working directory is not inside a git repository. */
+  isRepo: boolean;
+  root: string | null;
+  /** Current branch name, or `null` when HEAD is detached. */
+  branch: string | null;
+  detached: boolean;
+  /** Short HEAD object name. */
+  head: string | null;
+  upstream: string | null;
+  ahead: number;
+  behind: number;
+  staged: StatusFileEntry[];
+  unstaged: StatusFileEntry[];
+  untracked: string[];
+  /** `true` when there are no staged, unstaged, or untracked changes. */
+  clean: boolean;
+  /** `true` when stage / unstage / commit actions are available. */
+  canWrite: boolean;
+}
+interface Commit {
+  hash: string;
+  shortHash: string;
+  author: string;
+  email: string;
+  /** Author date as epoch milliseconds. */
+  date: number;
+  subject: string;
+  body: string;
+  /** Ref names pointing at this commit (branches, tags, HEAD). */
+  refs: string[];
+  /** Full parent hashes — drives the commit graph. */
+  parents: string[];
+}
+interface GitLog {
+  isRepo: boolean;
+  commits: Commit[];
+  limit: number;
+  skip: number;
+  /** `true` when the page filled to `limit`, hinting at further history. */
+  hasMore: boolean;
+}
+interface LogArgs {
+  /** Number of commits to return (clamped to 1–200, default 30). */
+  limit?: number;
+  /** Commits to skip from the tip, for pagination (default 0). */
+  skip?: number;
+  /** Optional ref/branch to read history from (default: current HEAD). */
+  ref?: string;
+}
+interface Branch {
+  name: string;
+  current: boolean;
+  sha: string;
+  upstream: string | null;
+  subject: string;
+  ahead: number;
+  behind: number;
+  /** `true` when the upstream branch no longer exists. */
+  gone: boolean;
+}
+interface GitBranches {
+  isRepo: boolean;
+  current: string | null;
+  branches: Branch[];
+}
+interface DiffFile {
+  path: string;
+  additions: number;
+  deletions: number;
+  binary: boolean;
+}
+interface GitDiff {
+  isRepo: boolean;
+  staged: boolean;
+  path: string | null;
+  files: DiffFile[];
+  totalAdditions: number;
+  totalDeletions: number;
+  /** Unified patch text — populated when `path` targets a single file. */
+  patch: string | null;
+  /** `true` when `patch` was clipped to the internal char limit. */
+  truncated: boolean;
+}
+interface DiffArgs {
+  /** Limit the diff to a single path; omit for the whole tree. */
+  path?: string;
+  /** Diff the index against HEAD instead of the working tree. */
+  staged?: boolean;
+}
+interface CommitFile {
+  path: string;
+  additions: number;
+  deletions: number;
+  binary: boolean;
+  /** Change kind relative to the parent (add / modify / delete / rename …). */
+  status: FileStatusCode;
+}
+interface CommitDetail {
+  /** `false` when the working directory is not inside a git repository. */
+  isRepo: boolean;
+  /** `false` when the hash does not resolve to a commit. */
+  found: boolean;
+  hash: string;
+  shortHash: string;
+  author: string;
+  email: string;
+  /** Author date as epoch milliseconds. */
+  date: number;
+  committer: string;
+  committerEmail: string;
+  /** Commit date as epoch milliseconds. */
+  commitDate: number;
+  subject: string;
+  body: string;
+  parents: string[];
+  refs: string[];
+  files: CommitFile[];
+  totalAdditions: number;
+  totalDeletions: number;
+  /** Unified patch text for the commit, or `null` when omitted/unavailable. */
+  patch: string | null;
+  /** `true` when `patch` was clipped to the internal char limit. */
+  truncated: boolean;
+}
+interface ShowArgs {
+  /** Commit-ish to inspect (full or short hash). */
+  hash: string;
+  /** Include the full unified patch (default `true`). */
+  patch?: boolean;
+}
+interface StageArgs {
+  /** Paths to stage (`git add`). */
+  paths: string[];
+}
+interface UnstageArgs {
+  /** Paths to unstage (`git restore --staged`). */
+  paths: string[];
+}
+interface CommitArgs {
+  /** Commit message. */
+  message: string;
+}
+interface CommitResult {
+  /** `true` when the commit succeeded. */
+  ok: boolean;
+  /** Short hash of the new commit, or `null` on failure. */
+  hash: string | null;
+  /** Human-readable outcome (e.g. "nothing to commit"). */
+  message: string;
+  /** Working-tree status after the attempt. */
+  status: GitStatus;
+}
+/** The node API a consumer gets from `ctx.services.get('@devframes/service-git')`. */
+interface GitServiceApi {
+  status: () => Promise<GitStatus>;
+  log: (args?: LogArgs) => Promise<GitLog>;
+  show: (args: ShowArgs) => Promise<CommitDetail>;
+  diff: (args?: DiffArgs) => Promise<GitDiff>;
+  branches: () => Promise<GitBranches>;
+  stage: (args: StageArgs) => Promise<GitStatus>;
+  unstage: (args: UnstageArgs) => Promise<GitStatus>;
+  commit: (args: CommitArgs) => Promise<CommitResult>;
+}
+//#endregion
+//#region src/index.d.ts
+declare const GIT_SERVICE_PACKAGE = "@devframes/service-git";
+declare const GIT_SERVICE_SCOPE = "devframes:service:git";
+interface GitServiceOptions {
+  /**
+   * Repository directory to operate on. Defaults to the context's `cwd`; the
+   * repo root is discovered once (`rev-parse --show-toplevel`) and memoized.
+   */
+  cwd?: string;
+}
+declare module 'devframe' {
+  interface DevframeRpcServerFunctions {
+    'devframes:service:git:status': () => Promise<GitStatus>;
+    'devframes:service:git:log': (args?: LogArgs) => Promise<GitLog>;
+    'devframes:service:git:show': (args: ShowArgs) => Promise<CommitDetail>;
+    'devframes:service:git:diff': (args?: DiffArgs) => Promise<GitDiff>;
+    'devframes:service:git:branches': () => Promise<GitBranches>;
+    'devframes:service:git:stage': (args: StageArgs) => Promise<GitStatus>;
+    'devframes:service:git:unstage': (args: UnstageArgs) => Promise<GitStatus>;
+    'devframes:service:git:commit': (args: CommitArgs) => Promise<CommitResult>;
+  }
+  interface DevframeServicesRegistry {
+    '@devframes/service-git': GitServiceApi;
+  }
+  interface DevframeServicesScopeRegistry {
+    '@devframes/service-git': 'devframes:service:git';
+  }
+}
+/**
+ * The git wire service — read/write git operations shared over RPC by every
+ * plugin on the host, generalizing the utilities that used to live inside the
+ * git plugin. The exec wrapper and output parsers stay internal; consumers get
+ * the typed {@link GitServiceApi} in-process (`ctx.services.get`) and the same
+ * ops over `devframes:service:git:*` RPC. Write ops are always exposed —
+ * authorization is the host's connection-trust boundary. The service defines
+ * no `dump`/`snapshot`; a devframe bakes what it needs via `snapshotRpc`.
+ */
+declare function createGitService(options?: GitServiceOptions): DevframeServiceDefinition<GitServiceApi, GitServiceOptions>;
+//#endregion
+export { Branch, Commit, CommitArgs, CommitDetail, CommitFile, CommitResult, DiffArgs, DiffFile, FileStatusCode, GIT_SERVICE_PACKAGE, GIT_SERVICE_SCOPE, GitBranches, GitDiff, GitLog, GitServiceApi, GitServiceOptions, GitStatus, LogArgs, ShowArgs, StageArgs, StatusFileEntry, UnstageArgs, createGitService, createGitService as default };

package/dist/index.mjs

@@ -0,0 +1,764 @@
+import { defineRpcFunction } from "devframe";
+import { s } from "devframe/utils/simple-schema";
+import { execFile } from "node:child_process";
+import process from "node:process";
+import { promisify } from "node:util";
+//#region package.json
+var version = "0.9.1";
+//#endregion
+//#region src/git.ts
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 67108864;
+/**
+* Run a git command in `cwd`. Rejects when git exits non-zero — callers that
+* tolerate failure (e.g. "no upstream configured") should use {@link tryGit}.
+*/
+async function runGit(cwd, args) {
+	const { stdout, stderr } = await execFileAsync("git", args, {
+		cwd,
+		maxBuffer: MAX_BUFFER,
+		windowsHide: true,
+		env: {
+			...process.env,
+			GIT_PAGER: "cat",
+			GIT_OPTIONAL_LOCKS: "0",
+			LC_ALL: "C"
+		}
+	});
+	return {
+		stdout,
+		stderr
+	};
+}
+/** Run a git command, returning trimmed stdout or `null` when it fails. */
+async function tryGit(cwd, args) {
+	try {
+		const { stdout } = await runGit(cwd, args);
+		return stdout.replace(/\n$/, "");
+	} catch {
+		return null;
+	}
+}
+/**
+* Caller-supplied revisions must not start with `-`, which Git would parse as
+* an option before it treats the value as a revision.
+*/
+function isSafeRevision(rev) {
+	return rev.length > 0 && !rev.startsWith("-");
+}
+/** Resolve the repository root for `cwd`, or `null` when `cwd` is outside a repo. */
+async function resolveRepoRoot(cwd) {
+	return tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+}
+/** Split git output on a separator, dropping the trailing empty segment. */
+function splitClean(input, separator) {
+	return input.split(separator).filter((part) => part.length > 0);
+}
+/**
+* Extract a concise, single-line message from a failed `execFile` error.
+* git writes useful text (e.g. "nothing to commit") to stdout/stderr.
+*/
+function gitErrorMessage(error) {
+	const e = error;
+	return (e?.stderr || e?.stdout || e?.message || "git command failed").trim().split("\n")[0];
+}
+//#endregion
+//#region src/operations.ts
+/** Hard cap on returned patch text to keep payloads bounded. */
+const PATCH_CHAR_LIMIT = 2e5;
+const EMPTY_STATUS = {
+	isRepo: false,
+	root: null,
+	branch: null,
+	detached: false,
+	head: null,
+	upstream: null,
+	ahead: 0,
+	behind: 0,
+	staged: [],
+	unstaged: [],
+	untracked: [],
+	clean: true,
+	canWrite: false
+};
+function mapCode(code) {
+	switch (code) {
+		case "M": return "modified";
+		case "A": return "added";
+		case "D": return "deleted";
+		case "R": return "renamed";
+		case "C": return "copied";
+		case "T": return "type-changed";
+		case "U": return "unmerged";
+		default: return "unknown";
+	}
+}
+/**
+* Parse `git status --porcelain=v2 --branch -z` into a structured snapshot.
+* Records are NUL-separated; rename/copy (type `2`) entries consume an extra
+* token for the original path.
+*/
+function parseStatus(root, raw) {
+	const tokens = raw.split("\0");
+	const status = {
+		...EMPTY_STATUS,
+		isRepo: true,
+		root,
+		staged: [],
+		unstaged: [],
+		untracked: []
+	};
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (!token) continue;
+		if (token.startsWith("# ")) {
+			const [, key, ...rest] = token.split(" ");
+			const value = rest.join(" ");
+			if (key === "branch.head") {
+				if (value === "(detached)") {
+					status.detached = true;
+					status.branch = null;
+				} else status.branch = value;
+			} else if (key === "branch.oid" && value !== "(initial)") status.head = value.slice(0, 9);
+			else if (key === "branch.upstream") status.upstream = value;
+			else if (key === "branch.ab") {
+				const match = value.match(/\+(\d+)\s+-(\d+)/);
+				if (match) {
+					status.ahead = Number(match[1]);
+					status.behind = Number(match[2]);
+				}
+			}
+			continue;
+		}
+		if (token.startsWith("1 ") || token.startsWith("2 ")) {
+			const renamed = token.startsWith("2 ");
+			const fields = token.split(" ");
+			const xy = fields[1];
+			const x = xy[0];
+			const y = xy[1];
+			const path = fields.slice(renamed ? 9 : 8).join(" ");
+			const from = renamed ? tokens[++i] : void 0;
+			if (x !== ".") status.staged.push(from ? {
+				path,
+				from,
+				status: mapCode(x)
+			} : {
+				path,
+				status: mapCode(x)
+			});
+			if (y !== ".") status.unstaged.push({
+				path,
+				status: mapCode(y)
+			});
+			continue;
+		}
+		if (token.startsWith("u ")) {
+			const path = token.split(" ").slice(10).join(" ");
+			status.unstaged.push({
+				path,
+				status: "unmerged"
+			});
+			continue;
+		}
+		if (token.startsWith("? ")) status.untracked.push(token.slice(2));
+	}
+	status.clean = status.staged.length === 0 && status.unstaged.length === 0 && status.untracked.length === 0;
+	return status;
+}
+const LOG_FORMAT = [
+	"%H",
+	"%h",
+	"%P",
+	"%an",
+	"%ae",
+	"%aI",
+	"%D",
+	"%s",
+	"%b"
+].join("") + "";
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+function parseLog(raw) {
+	return splitClean(raw, "").map((record) => {
+		const [hash, shortHash, parents, author, email, isoDate, refs, subject, body] = record.replace(/^\n/, "").split("");
+		return {
+			hash,
+			shortHash,
+			author,
+			email,
+			date: Date.parse(isoDate),
+			subject,
+			body: (body ?? "").trim(),
+			refs: refs ? refs.split(", ").map((r) => r.trim()).filter(Boolean) : [],
+			parents: parents ? parents.split(" ").filter(Boolean) : []
+		};
+	});
+}
+const BRANCH_FORMAT = [
+	"%(refname:short)",
+	"%(objectname:short)",
+	"%(HEAD)",
+	"%(upstream:short)",
+	"%(upstream:track)",
+	"%(contents:subject)"
+].join("");
+function parseTrack(track) {
+	if (track.includes("gone")) return {
+		ahead: 0,
+		behind: 0,
+		gone: true
+	};
+	const ahead = track.match(/ahead (\d+)/);
+	const behind = track.match(/behind (\d+)/);
+	return {
+		ahead: ahead ? Number(ahead[1]) : 0,
+		behind: behind ? Number(behind[1]) : 0,
+		gone: false
+	};
+}
+function parseNumstat(raw) {
+	return splitClean(raw, "\n").map((line) => {
+		const [add, del, ...rest] = line.split("	");
+		const binary = add === "-" || del === "-";
+		return {
+			path: rest.join("	"),
+			additions: binary ? 0 : Number(add),
+			deletions: binary ? 0 : Number(del),
+			binary
+		};
+	});
+}
+const SHOW_FORMAT = [
+	"%H",
+	"%h",
+	"%P",
+	"%an",
+	"%ae",
+	"%aI",
+	"%cn",
+	"%ce",
+	"%cI",
+	"%D",
+	"%s",
+	"%b"
+].join("");
+const EMPTY_DETAIL = {
+	isRepo: false,
+	found: false,
+	hash: "",
+	shortHash: "",
+	author: "",
+	email: "",
+	date: 0,
+	committer: "",
+	committerEmail: "",
+	commitDate: 0,
+	subject: "",
+	body: "",
+	parents: [],
+	refs: [],
+	files: [],
+	totalAdditions: 0,
+	totalDeletions: 0,
+	patch: null,
+	truncated: false
+};
+function mapStatusCode(code) {
+	switch (code[0]) {
+		case "M": return "modified";
+		case "A": return "added";
+		case "D": return "deleted";
+		case "R": return "renamed";
+		case "C": return "copied";
+		case "T": return "type-changed";
+		case "U": return "unmerged";
+		default: return "unknown";
+	}
+}
+function parseNameStatus(raw) {
+	const map = /* @__PURE__ */ new Map();
+	for (const line of splitClean(raw, "\n")) {
+		const [code, ...paths] = line.split("	");
+		const path = paths[paths.length - 1];
+		if (path) map.set(path, mapStatusCode(code));
+	}
+	return map;
+}
+function parseCommitNumstat(raw, status) {
+	return splitClean(raw, "\n").map((line) => {
+		const [add, del, ...rest] = line.split("	");
+		const binary = add === "-" || del === "-";
+		const path = rest.join("	");
+		return {
+			path,
+			additions: binary ? 0 : Number(add),
+			deletions: binary ? 0 : Number(del),
+			binary,
+			status: status.get(path) ?? "modified"
+		};
+	});
+}
+function clipPatch(raw) {
+	return raw.length > PATCH_CHAR_LIMIT ? {
+		patch: raw.slice(0, PATCH_CHAR_LIMIT),
+		truncated: true
+	} : {
+		patch: raw,
+		truncated: false
+	};
+}
+/**
+* Build the git node API bound to a single working directory, with the repo
+* root resolved once (memoized). This is the surface returned to in-process
+* consumers and wrapped by the service's RPC.
+*/
+function createGitOps(cwd) {
+	let rootPromise;
+	const resolveRoot = () => rootPromise ??= resolveRepoRoot(cwd);
+	async function status() {
+		const root = await resolveRoot();
+		if (!root) return { ...EMPTY_STATUS };
+		const { stdout } = await runGit(cwd, [
+			"status",
+			"--porcelain=v2",
+			"--branch",
+			"-z"
+		]);
+		const result = parseStatus(root, stdout);
+		result.canWrite = true;
+		return result;
+	}
+	async function readCommit(hash, includePatch) {
+		if (!isSafeRevision(hash)) return {
+			...EMPTY_DETAIL,
+			isRepo: true
+		};
+		const meta = await tryGit(cwd, [
+			"show",
+			"-s",
+			`--format=${SHOW_FORMAT}`,
+			"--end-of-options",
+			hash
+		]);
+		if (meta == null) return {
+			...EMPTY_DETAIL,
+			isRepo: true
+		};
+		const [fullHash, shortHash, parents, author, email, authorDate, committer, committerEmail, committerDate, refs, subject, body] = meta.split("");
+		const numstat = await tryGit(cwd, [
+			"diff-tree",
+			"--no-commit-id",
+			"--numstat",
+			"-r",
+			"--root",
+			"--end-of-options",
+			hash
+		]);
+		const nameStatusRaw = await tryGit(cwd, [
+			"diff-tree",
+			"--no-commit-id",
+			"--name-status",
+			"-r",
+			"--root",
+			"--end-of-options",
+			hash
+		]);
+		const files = numstat ? parseCommitNumstat(numstat, nameStatusRaw ? parseNameStatus(nameStatusRaw) : /* @__PURE__ */ new Map()) : [];
+		let patch = null;
+		let truncated = false;
+		if (includePatch) {
+			const raw = await tryGit(cwd, [
+				"diff-tree",
+				"-p",
+				"--no-commit-id",
+				"-r",
+				"--root",
+				"--end-of-options",
+				hash
+			]);
+			if (raw != null) ({patch, truncated} = clipPatch(raw));
+		}
+		return {
+			isRepo: true,
+			found: true,
+			hash: fullHash,
+			shortHash,
+			author,
+			email,
+			date: Date.parse(authorDate),
+			committer,
+			committerEmail,
+			commitDate: Date.parse(committerDate),
+			subject,
+			body: (body ?? "").trim(),
+			parents: parents ? parents.split(" ").filter(Boolean) : [],
+			refs: refs ? refs.split(", ").map((r) => r.trim()).filter(Boolean) : [],
+			files,
+			totalAdditions: files.reduce((sum, f) => sum + f.additions, 0),
+			totalDeletions: files.reduce((sum, f) => sum + f.deletions, 0),
+			patch,
+			truncated
+		};
+	}
+	return {
+		status,
+		async log(args = {}) {
+			const limit = clamp(Math.trunc(args.limit ?? 30), 1, 200);
+			const skip = Math.max(0, Math.trunc(args.skip ?? 0));
+			const ref = args.ref?.trim() || void 0;
+			if (!await resolveRoot()) return {
+				isRepo: false,
+				commits: [],
+				limit,
+				skip,
+				hasMore: false
+			};
+			const command = [
+				"log",
+				"--topo-order",
+				`--max-count=${limit}`,
+				`--skip=${skip}`,
+				`--pretty=format:${LOG_FORMAT}`
+			];
+			if (ref) {
+				if (!isSafeRevision(ref)) return {
+					isRepo: true,
+					commits: [],
+					limit,
+					skip,
+					hasMore: false
+				};
+				command.push("--end-of-options", ref);
+			}
+			const raw = await tryGit(cwd, command);
+			const commits = raw ? parseLog(raw) : [];
+			return {
+				isRepo: true,
+				commits,
+				limit,
+				skip,
+				hasMore: commits.length === limit
+			};
+		},
+		async show(args) {
+			const hash = (args?.hash ?? "").trim();
+			const includePatch = args?.patch ?? true;
+			if (!await resolveRoot() || !hash) return { ...EMPTY_DETAIL };
+			return readCommit(hash, includePatch);
+		},
+		async diff(args = {}) {
+			const { path, staged = false } = args;
+			if (!await resolveRoot()) return {
+				isRepo: false,
+				staged,
+				path: path ?? null,
+				files: [],
+				totalAdditions: 0,
+				totalDeletions: 0,
+				patch: null,
+				truncated: false
+			};
+			const base = staged ? ["diff", "--cached"] : ["diff"];
+			const scope = path ? ["--", path] : [];
+			const numstatRaw = await tryGit(cwd, [
+				...base,
+				"--numstat",
+				...scope
+			]);
+			const files = numstatRaw ? parseNumstat(numstatRaw) : [];
+			let patch = null;
+			let truncated = false;
+			if (path) {
+				const { stdout } = await runGit(cwd, [...base, ...scope]);
+				({patch, truncated} = clipPatch(stdout));
+			}
+			return {
+				isRepo: true,
+				staged,
+				path: path ?? null,
+				files,
+				totalAdditions: files.reduce((sum, f) => sum + f.additions, 0),
+				totalDeletions: files.reduce((sum, f) => sum + f.deletions, 0),
+				patch,
+				truncated
+			};
+		},
+		async branches() {
+			if (!await resolveRoot()) return {
+				isRepo: false,
+				current: null,
+				branches: []
+			};
+			const raw = await tryGit(cwd, [
+				"for-each-ref",
+				`--format=${BRANCH_FORMAT}`,
+				"refs/heads"
+			]);
+			if (!raw) return {
+				isRepo: true,
+				current: null,
+				branches: []
+			};
+			let current = null;
+			const branches = splitClean(raw, "\n").map((line) => {
+				const [name, sha, head, upstream, track, subject] = line.split("");
+				const isCurrent = head === "*";
+				if (isCurrent) current = name;
+				return {
+					name,
+					current: isCurrent,
+					sha,
+					upstream: upstream || null,
+					subject: subject ?? "",
+					...parseTrack(track ?? "")
+				};
+			});
+			branches.sort((a, b) => Number(b.current) - Number(a.current));
+			return {
+				isRepo: true,
+				current,
+				branches
+			};
+		},
+		async stage(args) {
+			const paths = args?.paths ?? [];
+			if (await resolveRoot() && paths.length > 0) await runGit(cwd, [
+				"add",
+				"--",
+				...paths
+			]);
+			return status();
+		},
+		async unstage(args) {
+			const paths = args?.paths ?? [];
+			if (await resolveRoot() && paths.length > 0) await runGit(cwd, [
+				"restore",
+				"--staged",
+				"--",
+				...paths
+			]);
+			return status();
+		},
+		async commit(args) {
+			const message = (args?.message ?? "").trim();
+			if (!await resolveRoot()) return {
+				ok: false,
+				hash: null,
+				message: "Not a git repository.",
+				status: await status()
+			};
+			if (!message) return {
+				ok: false,
+				hash: null,
+				message: "Commit message is required.",
+				status: await status()
+			};
+			try {
+				await runGit(cwd, [
+					"commit",
+					"-m",
+					message
+				]);
+				return {
+					ok: true,
+					hash: await tryGit(cwd, [
+						"rev-parse",
+						"--short",
+						"HEAD"
+					]),
+					message: "Committed.",
+					status: await status()
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					hash: null,
+					message: gitErrorMessage(error),
+					status: await status()
+				};
+			}
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+const GIT_SERVICE_PACKAGE = "@devframes/service-git";
+const GIT_SERVICE_SCOPE = "devframes:service:git";
+const commitSchema = s.object({
+	hash: s.string(),
+	shortHash: s.string(),
+	author: s.string(),
+	email: s.string(),
+	date: s.number(),
+	subject: s.string(),
+	body: s.string(),
+	refs: s.array(s.string()),
+	parents: s.array(s.string())
+});
+const gitLogSchema = s.object({
+	isRepo: s.boolean(),
+	commits: s.array(commitSchema),
+	limit: s.number(),
+	skip: s.number(),
+	hasMore: s.boolean()
+});
+const fileStatusCodeSchema = s.picklist([
+	"modified",
+	"added",
+	"deleted",
+	"renamed",
+	"copied",
+	"type-changed",
+	"unmerged",
+	"unknown"
+]);
+const commitDetailSchema = s.object({
+	isRepo: s.boolean(),
+	found: s.boolean(),
+	hash: s.string(),
+	shortHash: s.string(),
+	author: s.string(),
+	email: s.string(),
+	date: s.number(),
+	committer: s.string(),
+	committerEmail: s.string(),
+	commitDate: s.number(),
+	subject: s.string(),
+	body: s.string(),
+	parents: s.array(s.string()),
+	refs: s.array(s.string()),
+	files: s.array(s.object({
+		path: s.string(),
+		additions: s.number(),
+		deletions: s.number(),
+		binary: s.boolean(),
+		status: fileStatusCodeSchema
+	})),
+	totalAdditions: s.number(),
+	totalDeletions: s.number(),
+	patch: s.nullable(s.string()),
+	truncated: s.boolean()
+});
+const gitDiffSchema = s.object({
+	isRepo: s.boolean(),
+	staged: s.boolean(),
+	path: s.nullable(s.string()),
+	files: s.array(s.object({
+		path: s.string(),
+		additions: s.number(),
+		deletions: s.number(),
+		binary: s.boolean()
+	})),
+	totalAdditions: s.number(),
+	totalDeletions: s.number(),
+	patch: s.nullable(s.string()),
+	truncated: s.boolean()
+});
+/**
+* The git wire service — read/write git operations shared over RPC by every
+* plugin on the host, generalizing the utilities that used to live inside the
+* git plugin. The exec wrapper and output parsers stay internal; consumers get
+* the typed {@link GitServiceApi} in-process (`ctx.services.get`) and the same
+* ops over `devframes:service:git:*` RPC. Write ops are always exposed —
+* authorization is the host's connection-trust boundary. The service defines
+* no `dump`/`snapshot`; a devframe bakes what it needs via `snapshotRpc`.
+*/
+function createGitService(options) {
+	return {
+		package: GIT_SERVICE_PACKAGE,
+		version,
+		scope: GIT_SERVICE_SCOPE,
+		options,
+		setup(ctx, { options }) {
+			const ops = createGitOps(options?.cwd ?? ctx.cwd);
+			ctx.rpc.register(defineRpcFunction({
+				name: "status",
+				type: "query",
+				jsonSerializable: true,
+				agent: {
+					title: "Git status",
+					description: "Working-tree status of the inspected repository: current branch, ahead/behind counts, and every staged/unstaged/untracked file. Safe to call freely."
+				},
+				handler: () => ops.status()
+			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "log",
+				type: "query",
+				jsonSerializable: true,
+				args: [s.object({
+					limit: s.optional(s.number()),
+					skip: s.optional(s.number()),
+					ref: s.optional(s.string())
+				})],
+				returns: gitLogSchema,
+				agent: {
+					title: "Git log",
+					description: "Commit history of the inspected repository, newest first. Paginate with limit (1-200, default 30) and skip; pass ref to read another branch. Safe to call freely."
+				},
+				handler: (args = {}) => ops.log(args)
+			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "show",
+				type: "query",
+				jsonSerializable: true,
+				args: [s.object({
+					hash: s.string(),
+					patch: s.optional(s.boolean())
+				})],
+				returns: commitDetailSchema,
+				agent: {
+					title: "Git show",
+					description: "Full detail of one commit by hash: metadata, changed files, and the unified patch (pass patch: false to skip it for large commits). Safe to call freely."
+				},
+				handler: (args) => ops.show(args)
+			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "diff",
+				type: "query",
+				jsonSerializable: true,
+				args: [s.object({
+					path: s.optional(s.string()),
+					staged: s.optional(s.boolean())
+				})],
+				returns: gitDiffSchema,
+				agent: {
+					title: "Git diff",
+					description: "Unified diff of uncommitted changes — the working tree by default, the index with staged: true, one file with path. Safe to call freely."
+				},
+				handler: (args = {}) => ops.diff(args)
+			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "branches",
+				type: "query",
+				jsonSerializable: true,
+				agent: {
+					title: "Git branches",
+					description: "List local branches with tracking state (ahead/behind, gone upstreams) and the current branch. Safe to call freely."
+				},
+				handler: () => ops.branches()
+			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "stage",
+				type: "action",
+				jsonSerializable: true,
+				handler: (args) => ops.stage(args)
+			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "unstage",
+				type: "action",
+				jsonSerializable: true,
+				handler: (args) => ops.unstage(args)
+			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "commit",
+				type: "action",
+				jsonSerializable: true,
+				handler: (args) => ops.commit(args)
+			}));
+			return ops;
+		}
+	};
+}
+//#endregion
+export { GIT_SERVICE_PACKAGE, GIT_SERVICE_SCOPE, createGitService, createGitService as default };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@devframes/service-git",
+  "type": "module",
+  "version": "0.9.1",
+  "description": "Devframe wire service exposing read/write git operations (status, log, show, diff, branches, stage, unstage, commit) over RPC.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/devframes/devframe#readme",
+  "repository": {
+    "directory": "services/git",
+    "type": "git",
+    "url": "git+https://github.com/devframes/devframe.git"
+  },
+  "bugs": "https://github.com/devframes/devframe/issues",
+  "keywords": [
+    "devframe",
+    "devframe-service",
+    "devtools",
+    "git"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "devframe": "0.9.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsdown": "^0.22.14",
+    "vitest": "^4.1.10",
+    "devframe": "0.9.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}