@civilization/dsh-git-workbench 0.0.0-stage → 0.4.0

package/lib/index.js

@@ -0,0 +1,1274 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+// src/git-executor.ts
+const execFileAsync = promisify(execFile);
+/** Timeout in milliseconds for git operations */
+const GIT_TIMEOUT_MS = 15e3;
+/** Maximum stdout buffer for git diff / log output (8MB) */
+const GIT_MAX_BUFFER = 8388608;
+/** Vibrant IDEA-grade color palette for DAG branches */
+const LANE_PALETTE = [
+	"#388bfd",
+	"#2ea043",
+	"#f0883e",
+	"#a371f7",
+	"#db61a2",
+	"#39c5bb",
+	"#f9c513"
+];
+/**
+* Execute a git command in the target directory safely.
+* @param cwd - Working directory for the git execution.
+* @param args - Subcommand and arguments to pass to git.
+* @returns Raw stdout trimmed, or undefined if the execution failed.
+*/
+async function runGit(cwd, args) {
+	try {
+		const { stdout } = await execFileAsync("git", args, {
+			cwd,
+			timeout: GIT_TIMEOUT_MS,
+			maxBuffer: GIT_MAX_BUFFER,
+			windowsHide: true,
+			encoding: "utf8"
+		});
+		return stdout.trim();
+	} catch {
+		return;
+	}
+}
+/**
+* Detailed execution result returning stdout, stderr, and success code.
+* @param cwd - Working directory.
+* @param args - Arguments.
+* @returns Standard execution details.
+*/
+async function runGitDetailed(cwd, args) {
+	try {
+		const { stdout, stderr } = await execFileAsync("git", args, {
+			cwd,
+			timeout: GIT_TIMEOUT_MS,
+			maxBuffer: GIT_MAX_BUFFER,
+			windowsHide: true,
+			encoding: "utf8"
+		});
+		return {
+			ok: true,
+			stdout: stdout.trim(),
+			stderr: stderr.trim()
+		};
+	} catch (err) {
+		const error = err;
+		return {
+			ok: false,
+			stdout: (error.stdout ?? "").trim(),
+			stderr: (error.stderr || error.message || String(err)).trim()
+		};
+	}
+}
+/**
+* Check if the target directory is inside a valid git repository worktree.
+* @param cwd - Target directory.
+* @returns Whether cwd is a git repository.
+*/
+async function checkIsGitRepo(cwd) {
+	return await runGit(cwd, ["rev-parse", "--is-inside-work-tree"]) === "true";
+}
+/**
+* Get the absolute top-level directory of the git repository.
+* @param cwd - Target directory.
+* @returns Top-level directory path, or undefined.
+*/
+async function getGitRoot(cwd) {
+	const root = await runGit(cwd, ["rev-parse", "--show-toplevel"]);
+	return root ? root.replaceAll("\\", "/") : void 0;
+}
+/**
+* Map porcelain status character to normalized status code.
+* @param char - Status character from git porcelain.
+* @returns Normalized status code.
+*/
+function parseStatusCode(char) {
+	switch (char) {
+		case "A": return "added";
+		case "D": return "deleted";
+		case "R": return "renamed";
+		case "C": return "copied";
+		case "?": return "untracked";
+		default: return "modified";
+	}
+}
+/**
+* Parse one porcelain file status line.
+* @param line - Raw line from `git status --porcelain=v1`.
+* @returns Status entries for staged, unstaged, or untracked categories.
+*/
+function parsePorcelainLine(line) {
+	if (line.length < 3) return {};
+	const x = line[0] ?? " ";
+	const y = line[1] ?? " ";
+	const rawPath = line.slice(3).trim();
+	let path = rawPath;
+	let originalPath;
+	if (rawPath.includes(" -> ")) {
+		const parts = rawPath.split(" -> ");
+		originalPath = parts[0]?.replaceAll("\"", "");
+		path = parts[1]?.replaceAll("\"", "") ?? rawPath;
+	} else path = rawPath.replaceAll("\"", "");
+	if (x === "?" && y === "?") return { untracked: {
+		path,
+		status: "untracked",
+		staged: false
+	} };
+	const result = {};
+	if (x !== " " && x !== "?") result.staged = {
+		path,
+		...originalPath !== void 0 ? { originalPath } : {},
+		status: parseStatusCode(x),
+		staged: true
+	};
+	if (y !== " " && y !== "?") result.unstaged = {
+		path,
+		...originalPath !== void 0 ? { originalPath } : {},
+		status: parseStatusCode(y),
+		staged: false
+	};
+	return result;
+}
+/**
+* Query full git repository status for the given directory.
+* @param cwd - Target directory.
+* @returns Complete status summary.
+*/
+async function getGitStatus(cwd) {
+	if (!await checkIsGitRepo(cwd)) return {
+		isRepo: false,
+		ahead: 0,
+		behind: 0,
+		staged: [],
+		unstaged: [],
+		untracked: [],
+		totalChanges: 0
+	};
+	const rootPath = await getGitRoot(cwd);
+	const porcelain = await runGit(cwd, [
+		"status",
+		"--porcelain=v1",
+		"-b"
+	]);
+	let branch = "HEAD";
+	let upstream;
+	let ahead = 0;
+	let behind = 0;
+	const staged = [];
+	const unstaged = [];
+	const untracked = [];
+	if (porcelain) {
+		const lines = porcelain.split(/\r?\n/);
+		for (const line of lines) {
+			if (!line) continue;
+			if (line.startsWith("## ")) {
+				const branchHeader = line.slice(3).trim();
+				const bracketIndex = branchHeader.indexOf(" [");
+				const branchPart = bracketIndex !== -1 ? branchHeader.slice(0, bracketIndex) : branchHeader;
+				if (branchPart.includes("...")) {
+					const [b, u] = branchPart.split("...");
+					branch = b ?? "HEAD";
+					upstream = u;
+				} else branch = branchPart;
+				if (bracketIndex !== -1) {
+					const aheadMatch = /ahead (\d+)/.exec(branchHeader);
+					if (aheadMatch?.[1]) ahead = Number.parseInt(aheadMatch[1], 10);
+					const behindMatch = /behind (\d+)/.exec(branchHeader);
+					if (behindMatch?.[1]) behind = Number.parseInt(behindMatch[1], 10);
+				}
+			} else {
+				const parsed = parsePorcelainLine(line);
+				if (parsed.staged) staged.push(parsed.staged);
+				if (parsed.unstaged) unstaged.push(parsed.unstaged);
+				if (parsed.untracked) untracked.push(parsed.untracked);
+			}
+		}
+	}
+	let headCommit;
+	const headRaw = await runGit(cwd, [
+		"log",
+		"-1",
+		"--pretty=format:%H%x1f%h%x1f%s"
+	]);
+	if (headRaw) {
+		const [hash, shortHash, message] = headRaw.split("");
+		if (hash && shortHash && message !== void 0) headCommit = {
+			hash,
+			shortHash,
+			message
+		};
+	}
+	let totalCommitsCount;
+	const countRaw = await runGit(cwd, [
+		"rev-list",
+		"--count",
+		"HEAD"
+	]);
+	if (countRaw) {
+		const parsed = Number.parseInt(countRaw.trim(), 10);
+		if (!Number.isNaN(parsed)) totalCommitsCount = parsed;
+	}
+	return {
+		isRepo: true,
+		...rootPath !== void 0 ? { rootPath } : {},
+		branch,
+		...upstream !== void 0 ? { upstream } : {},
+		ahead,
+		behind,
+		...headCommit !== void 0 ? { headCommit } : {},
+		...totalCommitsCount !== void 0 ? { totalCommitsCount } : {},
+		staged,
+		unstaged,
+		untracked,
+		totalChanges: staged.length + unstaged.length + untracked.length
+	};
+}
+/**
+* Parse refs from git %D format (e.g. "HEAD -> master, origin/master, tag: v0.1").
+* @param refStr - Raw refs string.
+* @returns Normalized list of clean ref names.
+*/
+function parseCommitRefs(refStr) {
+	if (!refStr.trim()) return [];
+	const parts = refStr.split(",");
+	const refs = [];
+	for (const part of parts) {
+		const trimmed = part.trim();
+		if (!trimmed) continue;
+		if (trimmed.startsWith("HEAD -> ")) refs.push(trimmed.slice(8));
+		else refs.push(trimmed);
+	}
+	return refs;
+}
+/**
+* Compute DAG topology lanes and vector paths for commits (IntelliJ IDEA style graph).
+* Implements mainline pinning (trunk commits firmly anchored to lane 0) and smooth lane allocations.
+* @param rawCommits - Chronological descending commits with parents.
+* @returns Commits augmented with lane indices, lane colors, and connecting paths.
+*/
+function buildDagTopology(rawCommits) {
+	const activeLanes = [];
+	const result = [];
+	for (const item of rawCommits) {
+		let lane = activeLanes.indexOf(item.hash);
+		if (lane === -1) {
+			if (activeLanes.length === 0 || activeLanes[0] === null) {
+				lane = 0;
+				if (activeLanes.length === 0) activeLanes.push(null);
+				else activeLanes[0] = null;
+			} else {
+				let emptySlot = -1;
+				for (let l = 1; l < activeLanes.length; l++) if (activeLanes[l] === null) {
+					emptySlot = l;
+					break;
+				}
+				if (emptySlot !== -1) lane = emptySlot;
+				else {
+					lane = activeLanes.length;
+					activeLanes.push(null);
+				}
+			}
+		}
+		const laneColor = LANE_PALETTE[lane % LANE_PALETTE.length] ?? "#388bfd";
+		activeLanes[lane] = null;
+		const paths = [];
+		const [firstParent, ...otherParents] = item.parents;
+		if (firstParent) {
+			const existingParentLane = activeLanes.indexOf(firstParent);
+			if (lane === 0) {
+				if (existingParentLane !== -1 && existingParentLane !== 0) {
+					activeLanes[existingParentLane] = null;
+					paths.push({
+						fromLane: existingParentLane,
+						toLane: 0,
+						kind: "merge",
+						color: laneColor
+					});
+				}
+				activeLanes[0] = firstParent;
+				paths.push({
+					fromLane: 0,
+					toLane: 0,
+					kind: "straight",
+					color: laneColor
+				});
+			} else if (existingParentLane !== -1) paths.push({
+				fromLane: lane,
+				toLane: existingParentLane,
+				kind: "merge",
+				color: laneColor
+			});
+			else {
+				activeLanes[lane] = firstParent;
+				paths.push({
+					fromLane: lane,
+					toLane: lane,
+					kind: "straight",
+					color: laneColor
+				});
+			}
+		}
+		for (const otherParent of otherParents) {
+			const existingLane = activeLanes.indexOf(otherParent);
+			if (existingLane !== -1) paths.push({
+				fromLane: lane,
+				toLane: existingLane,
+				kind: "merge",
+				color: LANE_PALETTE[existingLane % LANE_PALETTE.length] ?? laneColor
+			});
+			else {
+				let emptySlot = -1;
+				for (let l = 1; l < activeLanes.length; l++) if (activeLanes[l] === null) {
+					emptySlot = l;
+					break;
+				}
+				const newLane = emptySlot !== -1 ? emptySlot : Math.max(1, activeLanes.length);
+				if (emptySlot !== -1) activeLanes[emptySlot] = otherParent;
+				else {
+					while (activeLanes.length < newLane) activeLanes.push(null);
+					activeLanes[newLane] = otherParent;
+				}
+				const branchColor = LANE_PALETTE[newLane % LANE_PALETTE.length] ?? laneColor;
+				paths.push({
+					fromLane: lane,
+					toLane: newLane,
+					kind: "fork",
+					color: branchColor
+				});
+			}
+		}
+		for (let l = 0; l < activeLanes.length; l++) if (l !== lane && activeLanes[l] !== null) paths.push({
+			fromLane: l,
+			toLane: l,
+			kind: "straight",
+			color: LANE_PALETTE[l % LANE_PALETTE.length] ?? "#388bfd"
+		});
+		while (activeLanes.length > 0 && activeLanes.at(-1) === null) activeLanes.pop();
+		result.push({
+			hash: item.hash,
+			shortHash: item.shortHash,
+			author: item.author,
+			authorEmail: item.authorEmail,
+			relativeDate: item.relativeDate,
+			date: item.date,
+			subject: item.subject,
+			parents: item.parents,
+			refs: item.refs,
+			lane,
+			laneColor,
+			paths
+		});
+	}
+	return result;
+}
+/**
+* Query recent git commit history with DAG graph topology for the given directory.
+* @param cwd - Target directory.
+* @param maxCount - Maximum number of commits to retrieve (defaults to 50).
+* @returns Ordered list of recent commits with topology paths.
+*/
+async function getGitLog(cwd, maxCount = 50) {
+	if (!await checkIsGitRepo(cwd)) return [];
+	const raw = await runGit(cwd, [
+		"log",
+		"-n",
+		String(maxCount),
+		"--pretty=format:%H%x1f%h%x1f%an%x1f%ae%x1f%ar%x1f%ad%x1f%s%x1f%P%x1f%D"
+	]);
+	if (!raw) return [];
+	const rawCommits = [];
+	const lines = raw.split(/\r?\n/);
+	for (const line of lines) {
+		if (!line) continue;
+		const parts = line.split("");
+		if (parts.length >= 7 && parts[0] && parts[1] && parts[2] && parts[3] && parts[4] && parts[5] && parts[6] !== void 0) {
+			const parentStr = parts[7] ?? "";
+			const parents = parentStr.trim() ? parentStr.trim().split(/\s+/) : [];
+			const refs = parseCommitRefs(parts[8] ?? "");
+			rawCommits.push({
+				hash: parts[0],
+				shortHash: parts[1],
+				author: parts[2],
+				authorEmail: parts[3],
+				relativeDate: parts[4],
+				date: parts[5],
+				subject: parts[6],
+				parents,
+				refs
+			});
+		}
+	}
+	return buildDagTopology(rawCommits);
+}
+/**
+* Query details and changed files for a specific commit.
+* @param cwd - Working directory.
+* @param commitHash - Full or abbreviated commit hash.
+* @returns Detailed commit information.
+*/
+async function getGitCommitDetails(cwd, commitHash) {
+	if (!await checkIsGitRepo(cwd)) return void 0;
+	const headRaw = await runGit(cwd, [
+		"show",
+		"--no-patch",
+		"--pretty=format:%H%x1f%h%x1f%an%x1f%ae%x1f%ar%x1f%ad%x1f%s%x1f%P%x1f%D%x1f%b",
+		commitHash
+	]);
+	if (!headRaw) return void 0;
+	const parts = headRaw.split("");
+	if (parts.length < 7 || !parts[0] || !parts[1] || !parts[2] || !parts[3] || !parts[4] || !parts[5] || parts[6] === void 0) return;
+	const parentStr = parts[7] ?? "";
+	const parents = parentStr.trim() ? parentStr.trim().split(/\s+/) : [];
+	const refs = parseCommitRefs(parts[8] ?? "");
+	const rawBody = (parts[9] ?? "").trim();
+	const body = rawBody.length > 0 ? rawBody : void 0;
+	const commit = {
+		hash: parts[0],
+		shortHash: parts[1],
+		author: parts[2],
+		authorEmail: parts[3],
+		relativeDate: parts[4],
+		date: parts[5],
+		subject: parts[6],
+		...body !== void 0 ? { body } : {},
+		parents,
+		refs
+	};
+	const numstatRaw = await runGit(cwd, [
+		"show",
+		"--numstat",
+		"--format=",
+		"-M",
+		commitHash
+	]);
+	const files = [];
+	let totalAdditions = 0;
+	let totalDeletions = 0;
+	if (numstatRaw) {
+		const lines = numstatRaw.split(/\r?\n/);
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			const match = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(line);
+			if (match && match[1] && match[2] && match[3]) {
+				const adds = match[1] === "-" ? 0 : Number.parseInt(match[1], 10);
+				const dels = match[2] === "-" ? 0 : Number.parseInt(match[2], 10);
+				const rawPath = match[3];
+				let path = rawPath;
+				let oldPath;
+				let status = "modified";
+				if (rawPath.includes(" => ")) {
+					status = "renamed";
+					const braceMatch = /^(.*)\{(.+) => (.+)\}(.*)$/.exec(rawPath);
+					if (braceMatch && braceMatch[1] !== void 0 && braceMatch[2] !== void 0 && braceMatch[3] !== void 0 && braceMatch[4] !== void 0) {
+						oldPath = `${braceMatch[1]}${braceMatch[2]}${braceMatch[4]}`;
+						path = `${braceMatch[1]}${braceMatch[3]}${braceMatch[4]}`;
+					} else {
+						const split = rawPath.split(" => ");
+						oldPath = split[0]?.trim();
+						path = split[1]?.trim() ?? rawPath;
+					}
+				}
+				totalAdditions += adds;
+				totalDeletions += dels;
+				files.push({
+					path,
+					...oldPath !== void 0 ? { oldPath } : {},
+					status,
+					additions: adds,
+					deletions: dels
+				});
+			}
+		}
+	}
+	return {
+		commit,
+		...body !== void 0 ? { body } : {},
+		...parents.length > 0 ? { parents } : {},
+		files,
+		totalAdditions,
+		totalDeletions
+	};
+}
+/**
+* Query git diff for specified file or current directory.
+* @param cwd - Target directory.
+* @param options - Diff parameters.
+* @returns Complete diff text and per-file parsed statistics.
+*/
+async function getGitDiff(cwd, options) {
+	if (!await checkIsGitRepo(cwd)) return {
+		files: [],
+		rawDiff: ""
+	};
+	const args = [];
+	if (options?.commit) args.push("show", "--format=", "--patch", options.commit);
+	else {
+		args.push("diff");
+		if (options?.staged) args.push("--staged");
+	}
+	if (options?.path) args.push("--", options.path);
+	const rawDiff = await runGit(cwd, args) ?? "";
+	if (!rawDiff) return {
+		files: [],
+		rawDiff: ""
+	};
+	const files = [];
+	const fileChunks = rawDiff.split(/^diff --git /m);
+	for (const chunk of fileChunks) {
+		if (!chunk.trim()) continue;
+		const firstLineEnd = chunk.indexOf("\n");
+		const firstLine = firstLineEnd !== -1 ? chunk.slice(0, firstLineEnd).trim() : chunk.trim();
+		const match = /a\/(.+?) b\/(.+?)$/.exec(firstLine);
+		const filePath = match?.[2] ?? match?.[1] ?? "unknown";
+		const oldPath = match?.[1] !== match?.[2] ? match?.[1] : void 0;
+		let additions = 0;
+		let deletions = 0;
+		const lines = chunk.split("\n");
+		for (const l of lines) if (l.startsWith("+") && !l.startsWith("+++")) additions++;
+		else if (l.startsWith("-") && !l.startsWith("---")) deletions++;
+		files.push({
+			path: filePath,
+			...oldPath !== void 0 ? { oldPath } : {},
+			status: "modified",
+			diffText: `diff --git ${chunk}`,
+			additions,
+			deletions
+		});
+	}
+	return {
+		files,
+		rawDiff
+	};
+}
+/**
+* Query local and remote branches.
+* @param cwd - Target directory.
+* @returns Aggregated branch summary.
+*/
+async function getGitAllBranches(cwd) {
+	if (!await checkIsGitRepo(cwd)) return {
+		local: [],
+		remote: []
+	};
+	const raw = await runGit(cwd, [
+		"branch",
+		"-a",
+		"-vv",
+		"--list"
+	]);
+	if (!raw) return {
+		local: [],
+		remote: []
+	};
+	const local = [];
+	const remote = [];
+	let current;
+	const lines = raw.split(/\r?\n/);
+	for (const line of lines) {
+		if (!line.trim()) continue;
+		const isCurrent = line.startsWith("*");
+		const cleanLine = line.slice(2).trim();
+		if (cleanLine.includes("->")) continue;
+		const spaceIndex = cleanLine.indexOf(" ");
+		const fullName = spaceIndex !== -1 ? cleanLine.slice(0, spaceIndex) : cleanLine;
+		let upstream;
+		let ahead;
+		let behind;
+		const bracketStart = cleanLine.indexOf("[");
+		const bracketEnd = cleanLine.indexOf("]");
+		if (bracketStart !== -1 && bracketEnd > bracketStart) {
+			const info = cleanLine.slice(bracketStart + 1, bracketEnd);
+			const colonIndex = info.indexOf(":");
+			upstream = colonIndex !== -1 ? info.slice(0, colonIndex).trim() : info.trim();
+			const aheadMatch = /ahead (\d+)/.exec(info);
+			if (aheadMatch?.[1]) ahead = Number.parseInt(aheadMatch[1], 10);
+			const behindMatch = /behind (\d+)/.exec(info);
+			if (behindMatch?.[1]) behind = Number.parseInt(behindMatch[1], 10);
+		}
+		if (isCurrent) current = fullName;
+		if (fullName.startsWith("remotes/")) {
+			const remoteName = fullName.replace(/^remotes\//, "");
+			remote.push({
+				name: remoteName,
+				isCurrent: false
+			});
+		} else local.push({
+			name: fullName,
+			isCurrent,
+			...upstream !== void 0 ? { upstream } : {},
+			...ahead !== void 0 ? { ahead } : {},
+			...behind !== void 0 ? { behind } : {}
+		});
+	}
+	return {
+		...current !== void 0 ? { current } : {},
+		local,
+		remote
+	};
+}
+/**
+* Checkout an existing branch or create a new branch.
+* @param cwd - Target directory.
+* @param branch - Branch name to switch to.
+* @param createNew - Whether to create a new branch (-b).
+* @returns Operation result.
+*/
+async function gitCheckout(cwd, branch, createNew) {
+	const cleanBranch = branch.trim();
+	if (!cleanBranch) return {
+		success: false,
+		message: "Branch name cannot be empty"
+	};
+	const res = await runGitDetailed(cwd, createNew ? [
+		"checkout",
+		"-b",
+		cleanBranch
+	] : ["checkout", cleanBranch]);
+	return {
+		success: res.ok,
+		message: res.ok ? `Checked out branch ${cleanBranch}` : res.stderr || "Checkout failed",
+		output: res.stdout || res.stderr
+	};
+}
+/**
+* Stage files to index.
+* @param cwd - Target directory.
+* @param paths - Specific file paths or 'all'.
+* @returns Operation result.
+*/
+async function gitStage(cwd, paths) {
+	const res = await runGitDetailed(cwd, paths === "all" ? ["add", "-A"] : [
+		"add",
+		"--",
+		...paths
+	]);
+	return {
+		success: res.ok,
+		message: res.ok ? "Files staged successfully" : res.stderr || "Stage failed",
+		output: res.stdout || res.stderr
+	};
+}
+/**
+* Unstage files from index.
+* @param cwd - Target directory.
+* @param paths - Specific file paths or 'all'.
+* @returns Operation result.
+*/
+async function gitUnstage(cwd, paths) {
+	const res = await runGitDetailed(cwd, paths === "all" ? ["reset", "HEAD"] : [
+		"reset",
+		"HEAD",
+		"--",
+		...paths
+	]);
+	return {
+		success: res.ok,
+		message: res.ok ? "Files unstaged successfully" : res.stderr || "Unstage failed",
+		output: res.stdout || res.stderr
+	};
+}
+/**
+* Discard working tree changes for specified files.
+* @param cwd - Target directory.
+* @param paths - Specific file paths to discard.
+* @returns Operation result.
+*/
+async function gitDiscard(cwd, paths) {
+	if (paths.length === 0) return { success: true };
+	const resRestore = await runGitDetailed(cwd, [
+		"checkout",
+		"--",
+		...paths
+	]);
+	await runGitDetailed(cwd, [
+		"clean",
+		"-f",
+		"--",
+		...paths
+	]);
+	return {
+		success: resRestore.ok,
+		message: resRestore.ok ? "Changes discarded successfully" : resRestore.stderr || "Discard failed",
+		output: resRestore.stdout || resRestore.stderr
+	};
+}
+/**
+* Commit staged changes with message.
+* @param cwd - Target directory.
+* @param message - Commit message.
+* @returns Operation result.
+*/
+async function gitCommit(cwd, message) {
+	const trimmed = message.trim();
+	if (!trimmed) return {
+		success: false,
+		message: "Commit message cannot be empty"
+	};
+	const res = await runGitDetailed(cwd, [
+		"commit",
+		"-m",
+		trimmed
+	]);
+	return {
+		success: res.ok,
+		message: res.ok ? "Changes committed successfully" : res.stderr || "Commit failed",
+		output: res.stdout || res.stderr
+	};
+}
+/**
+* Fetch updates from remotes.
+* @param cwd - Target directory.
+* @returns Operation result.
+*/
+async function gitFetch(cwd) {
+	const res = await runGitDetailed(cwd, [
+		"fetch",
+		"--all",
+		"--prune"
+	]);
+	return {
+		success: res.ok,
+		message: res.ok ? "Fetched successfully" : res.stderr || "Fetch failed",
+		output: res.stdout || res.stderr
+	};
+}
+/**
+* Pull remote changes into current branch.
+* @param cwd - Target directory.
+* @returns Operation result.
+*/
+async function gitPull(cwd) {
+	const res = await runGitDetailed(cwd, ["pull"]);
+	return {
+		success: res.ok,
+		message: res.ok ? "Pulled successfully" : res.stderr || "Pull failed",
+		output: res.stdout || res.stderr
+	};
+}
+/**
+* Push local commits to remote upstream.
+* @param cwd - Target directory.
+* @returns Operation result.
+*/
+async function gitPush(cwd) {
+	const res = await runGitDetailed(cwd, ["push"]);
+	return {
+		success: res.ok,
+		message: res.ok ? "Pushed successfully" : res.stderr || "Push failed",
+		output: res.stdout || res.stderr
+	};
+}
+/**
+* Query all git tags in the repository sorted by creation date descending.
+* @param cwd - Target directory.
+* @returns Ordered list of Git tags with commit hashes and metadata.
+*/
+async function getGitTags(cwd) {
+	if (!await checkIsGitRepo(cwd)) return [];
+	const raw = await runGit(cwd, [
+		"for-each-ref",
+		"--sort=-creatordate",
+		"refs/tags",
+		"--format=%(refname:short)	%(objectname)	%(*objectname)	%(creatordate:iso)	%(creatordate:relative)	%(contents:subject)	%(taggername)	%(authorname)"
+	]);
+	if (!raw) return [];
+	const tags = [];
+	const lines = raw.split(/\r?\n/);
+	for (const line of lines) {
+		if (!line.trim()) continue;
+		const parts = line.split("	");
+		if (parts.length >= 6 && parts[0]) {
+			const name = parts[0];
+			const objectName = parts[1] ?? "";
+			const peeledHash = (parts[2] ?? "").trim();
+			const commitHash = peeledHash || objectName;
+			const isAnnotated = Boolean(peeledHash);
+			const date = parts[3] ?? "";
+			const relativeDate = parts[4] ?? "";
+			const message = parts[5] ?? "";
+			const author = parts[6] || parts[7] || "Unknown";
+			tags.push({
+				name,
+				commitHash,
+				shortHash: commitHash.slice(0, 7),
+				date,
+				relativeDate,
+				message,
+				author,
+				isAnnotated
+			});
+		}
+	}
+	return tags;
+}
+/**
+* Create a new git tag at the specified commit or HEAD.
+* @param cwd - Target directory.
+* @param name - Tag name (e.g. 'v1.0.0').
+* @param targetCommit - Optional commit hash (defaults to HEAD).
+* @param message - Optional annotation message. If provided, creates an annotated tag (-a).
+* @returns Operation result.
+*/
+async function gitCreateTag(cwd, name, targetCommit, message) {
+	const cleanName = name.trim();
+	if (!cleanName) return {
+		success: false,
+		message: "Tag name cannot be empty"
+	};
+	const args = ["tag"];
+	if (message && message.trim()) args.push("-a", cleanName, "-m", message.trim());
+	else args.push(cleanName);
+	if (targetCommit && targetCommit.trim()) args.push(targetCommit.trim());
+	const res = await runGitDetailed(cwd, args);
+	return {
+		success: res.ok,
+		message: res.ok ? `Tag '${cleanName}' created successfully` : res.stderr || "Failed to create tag",
+		output: res.stdout || res.stderr
+	};
+}
+/**
+* Delete a git tag.
+* @param cwd - Target directory.
+* @param name - Tag name to delete.
+* @returns Operation result.
+*/
+async function gitDeleteTag(cwd, name) {
+	const cleanName = name.trim();
+	if (!cleanName) return {
+		success: false,
+		message: "Tag name cannot be empty"
+	};
+	const res = await runGitDetailed(cwd, [
+		"tag",
+		"-d",
+		cleanName
+	]);
+	return {
+		success: res.ok,
+		message: res.ok ? `Tag '${cleanName}' deleted successfully` : res.stderr || "Failed to delete tag",
+		output: res.stdout || res.stderr
+	};
+}
+// src/tool.ts
+/**
+* Register git model tools (git_view and git_checkout) in the tools service.
+* @param ctx - Context carrying the tools service.
+* @param resolveDir - Resolver for the current agent or session working directory.
+*/
+function registerGitTool(ctx, resolveDir) {
+	ctx.inject(["tools"], (scope) => {
+		scope.effect(() => scope.tools.register(defineTool({
+			name: "git_view",
+			description: "Inspect the current project Git repository status, changed files, DAG commit tree, branch list, or code diffs.",
+			parameters: {
+				action: {
+					type: "string",
+					enum: [
+						"status",
+						"log",
+						"diff",
+						"branches",
+						"commit",
+						"tags"
+					],
+					description: "The Git query action: \"status\" (changes and branch info), \"log\" (commits with DAG topology rails), \"diff\" (code diffs), \"branches\" (branch list), \"commit\" (commit details), or \"tags\" (all repository tags)."
+				},
+				path: {
+					type: "string",
+					description: "Optional file path filter for diff or status inspection."
+				},
+				staged: {
+					type: "boolean",
+					description: "Whether to check staged changes when viewing diff (defaults to false for working tree changes)."
+				},
+				maxCount: {
+					type: "number",
+					description: "Maximum number of commits to retrieve when action is \"log\" (defaults to 30)."
+				},
+				commit: {
+					type: "string",
+					description: "Specific commit hash to inspect diff or details for."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: true
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: JSON.stringify(value, null, 2)
+				}]
+			},
+			async execute(args, exec) {
+				const cwd = resolveDir(exec.agent?.session.id);
+				switch (args.action ?? "status") {
+					case "log": {
+						const commits = (await getGitLog(cwd, args.maxCount ?? 30)).map((c) => ({
+							hash: c.hash,
+							shortHash: c.shortHash,
+							author: c.author,
+							authorEmail: c.authorEmail,
+							relativeDate: c.relativeDate,
+							date: c.date,
+							subject: c.subject,
+							parents: c.parents ? [...c.parents] : [],
+							refs: c.refs ? [...c.refs] : [],
+							...c.lane !== void 0 ? { lane: c.lane } : {},
+							...c.laneColor !== void 0 ? { laneColor: c.laneColor } : {}
+						}));
+						return {
+							action: "log",
+							count: commits.length,
+							commits
+						};
+					}
+					case "commit": {
+						if (!args.commit) return {
+							action: "commit",
+							error: "Missing commit parameter"
+						};
+						const details = await getGitCommitDetails(cwd, args.commit);
+						if (!details) return {
+							action: "commit",
+							found: false
+						};
+						return {
+							action: "commit",
+							found: true,
+							commit: {
+								hash: details.commit.hash,
+								shortHash: details.commit.shortHash,
+								author: details.commit.author,
+								date: details.commit.date,
+								subject: details.commit.subject
+							},
+							files: details.files.map((f) => ({
+								path: f.path,
+								status: f.status,
+								additions: f.additions,
+								deletions: f.deletions
+							})),
+							totalAdditions: details.totalAdditions,
+							totalDeletions: details.totalDeletions
+						};
+					}
+					case "diff": {
+						const diff = await getGitDiff(cwd, {
+							...args.path !== void 0 ? { path: args.path } : {},
+							...args.staged !== void 0 ? { staged: args.staged } : {},
+							...args.commit !== void 0 ? { commit: args.commit } : {}
+						});
+						return {
+							action: "diff",
+							files: diff.files.map((f) => ({
+								path: f.path,
+								additions: f.additions,
+								deletions: f.deletions
+							})),
+							rawDiff: diff.rawDiff
+						};
+					}
+					case "branches": {
+						const summary = await getGitAllBranches(cwd);
+						return {
+							action: "branches",
+							...summary.current !== void 0 ? { current: summary.current } : {},
+							local: summary.local.map((b) => ({
+								name: b.name,
+								isCurrent: b.isCurrent,
+								...b.upstream !== void 0 ? { upstream: b.upstream } : {},
+								...b.ahead !== void 0 ? { ahead: b.ahead } : {},
+								...b.behind !== void 0 ? { behind: b.behind } : {}
+							})),
+							remote: summary.remote.map((b) => ({
+								name: b.name,
+								isCurrent: b.isCurrent
+							}))
+						};
+					}
+					case "tags": {
+						const rawTags = await getGitTags(cwd);
+						return {
+							action: "tags",
+							total: rawTags.length,
+							tags: rawTags.map((t) => ({
+								name: t.name,
+								commitHash: t.commitHash,
+								shortHash: t.shortHash,
+								date: t.date,
+								relativeDate: t.relativeDate,
+								message: t.message,
+								author: t.author,
+								isAnnotated: t.isAnnotated
+							}))
+						};
+					}
+					default: {
+						const status = await getGitStatus(cwd);
+						return {
+							action: "status",
+							isRepo: status.isRepo,
+							...status.rootPath !== void 0 ? { rootPath: status.rootPath } : {},
+							...status.branch !== void 0 ? { branch: status.branch } : {},
+							...status.upstream !== void 0 ? { upstream: status.upstream } : {},
+							ahead: status.ahead,
+							behind: status.behind,
+							staged: status.staged.map((f) => ({
+								path: f.path,
+								status: f.status,
+								staged: f.staged
+							})),
+							unstaged: status.unstaged.map((f) => ({
+								path: f.path,
+								status: f.status,
+								staged: f.staged
+							})),
+							untracked: status.untracked.map((f) => ({
+								path: f.path,
+								status: f.status,
+								staged: f.staged
+							})),
+							totalChanges: status.totalChanges
+						};
+					}
+				}
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `git_view (${args.action ?? "status"})`,
+				rawInput: args
+			})
+		})), "experimental-git: register git_view tool");
+		scope.effect(() => scope.tools.register(defineTool({
+			name: "git_checkout",
+			description: "Switch branch or create and checkout a new branch in the current project Git repository.",
+			parameters: {
+				branch: {
+					type: "string",
+					required: true,
+					description: "The target branch name to switch to (e.g. \"feature/auth\", \"dev\", \"master\")."
+				},
+				create: {
+					type: "boolean",
+					description: "Whether to create a new branch from current HEAD and check it out (-b). Defaults to false."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: true
+				},
+				render: (_args, val) => {
+					const value = val;
+					return [{
+						type: "text",
+						text: value.success ? `Successfully checked out branch '${value.branch ?? ""}'.` : `Failed to checkout branch '${value.branch ?? ""}': ${value.message ?? ""}`
+					}];
+				}
+			},
+			async execute(args, exec) {
+				const cwd = resolveDir(exec.agent?.session.id);
+				const branch = args.branch.trim();
+				const result = await gitCheckout(cwd, branch, args.create ?? false);
+				return {
+					success: result.success,
+					branch,
+					message: result.message ?? ""
+				};
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `git_checkout ${args.create ? "-b " : ""}${args.branch}`,
+				rawInput: args
+			})
+		})), "experimental-git: register git_checkout tool");
+		scope.effect(() => scope.tools.register(defineTool({
+			name: "git_tag",
+			description: "Create or delete a Git tag in the current project repository.",
+			parameters: {
+				name: {
+					type: "string",
+					required: true,
+					description: "The tag name (e.g. \"v1.0.0\", \"release-20261020\")."
+				},
+				action: {
+					type: "string",
+					enum: ["create", "delete"],
+					description: "Tag operation: \"create\" (default) or \"delete\"."
+				},
+				commit: {
+					type: "string",
+					description: "Target commit hash to place the tag on when creating (defaults to current HEAD)."
+				},
+				message: {
+					type: "string",
+					description: "Optional annotation message for an annotated tag (git tag -a -m)."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: true
+				},
+				render: (_args, val) => {
+					const value = val;
+					return [{
+						type: "text",
+						text: value.message ?? (value.success ? "Success" : "Failed")
+					}];
+				}
+			},
+			async execute(args, exec) {
+				const cwd = resolveDir(exec.agent?.session.id);
+				const name = args.name.trim();
+				if ((args.action ?? "create") === "delete") {
+					const result = await gitDeleteTag(cwd, name);
+					return {
+						success: result.success,
+						name,
+						action: "delete",
+						message: result.message ?? ""
+					};
+				}
+				const result = await gitCreateTag(cwd, name, args.commit, args.message);
+				return {
+					success: result.success,
+					name,
+					action: "create",
+					message: result.message ?? ""
+				};
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `git_tag ${args.action ?? "create"} ${args.name}`,
+				rawInput: args
+			})
+		})), "experimental-git: register git_tag tool");
+	});
+}
+// src/index.ts
+/** Cordis plugin name */
+const name = "@civilization/dsh-git-workbench";
+/** Required host services */
+const inject = ["connection", "webServer"];
+/**
+* Apply the Git host plugin.
+* Sets up authenticated RPC handlers under `/git/*` and registers the model tool.
+* @param ctx - Context carrying the connection and optional session services.
+*/
+function apply(ctx) {
+	const host = ctx;
+	const resolveTargetDir = (sessionId) => {
+		if (sessionId) {
+			const liveCwd = host.sessions?.get(sessionId)?.header?.cwd;
+			if (liveCwd) return liveCwd;
+		}
+		return host.sandboxPolicy?.workspaceRoot ?? process.cwd();
+	};
+	host.connection.rpc.handle("/git", async (endpoint, payload, _signal) => {
+		const body = typeof payload === "object" && payload !== null ? payload : {};
+		const sessionId = typeof body.sessionId === "string" ? body.sessionId : void 0;
+		const cwd = typeof body.path === "string" ? body.path : resolveTargetDir(sessionId);
+		try {
+			if (endpoint === "status") return {
+				ok: true,
+				value: await getGitStatus(cwd)
+			};
+			if (endpoint === "log") return {
+				ok: true,
+				value: await getGitLog(cwd, typeof body.maxCount === "number" ? body.maxCount : 50)
+			};
+			if (endpoint === "commitDetails") return {
+				ok: true,
+				value: await getGitCommitDetails(cwd, typeof body.commit === "string" ? body.commit : "")
+			};
+			if (endpoint === "diff") {
+				const path = typeof body.filePath === "string" ? body.filePath : void 0;
+				const staged = typeof body.staged === "boolean" ? body.staged : false;
+				const commit = typeof body.commit === "string" ? body.commit : void 0;
+				return {
+					ok: true,
+					value: await getGitDiff(cwd, {
+						...path !== void 0 ? { path } : {},
+						staged,
+						...commit !== void 0 ? { commit } : {}
+					})
+				};
+			}
+			if (endpoint === "branches") return {
+				ok: true,
+				value: await getGitAllBranches(cwd)
+			};
+			if (endpoint === "checkout") return {
+				ok: true,
+				value: await gitCheckout(cwd, typeof body.branch === "string" ? body.branch : "", typeof body.create === "boolean" ? body.create : false)
+			};
+			if (endpoint === "stage") return {
+				ok: true,
+				value: await gitStage(cwd, Array.isArray(body.paths) ? body.paths : body.paths === "all" ? "all" : typeof body.path === "string" ? [body.path] : "all")
+			};
+			if (endpoint === "unstage") return {
+				ok: true,
+				value: await gitUnstage(cwd, Array.isArray(body.paths) ? body.paths : body.paths === "all" ? "all" : typeof body.path === "string" ? [body.path] : "all")
+			};
+			if (endpoint === "discard") return {
+				ok: true,
+				value: await gitDiscard(cwd, Array.isArray(body.paths) ? body.paths : typeof body.path === "string" ? [body.path] : [])
+			};
+			if (endpoint === "commit") return {
+				ok: true,
+				value: await gitCommit(cwd, typeof body.message === "string" ? body.message : "")
+			};
+			if (endpoint === "fetch") return {
+				ok: true,
+				value: await gitFetch(cwd)
+			};
+			if (endpoint === "pull") return {
+				ok: true,
+				value: await gitPull(cwd)
+			};
+			if (endpoint === "push") return {
+				ok: true,
+				value: await gitPush(cwd)
+			};
+			if (endpoint === "tags") return {
+				ok: true,
+				value: await getGitTags(cwd)
+			};
+			if (endpoint === "createTag") return {
+				ok: true,
+				value: await gitCreateTag(cwd, typeof body.name === "string" ? body.name : "", typeof body.commit === "string" ? body.commit : void 0, typeof body.message === "string" ? body.message : void 0)
+			};
+			if (endpoint === "deleteTag") return {
+				ok: true,
+				value: await gitDeleteTag(cwd, typeof body.name === "string" ? body.name : "")
+			};
+			return {
+				ok: false,
+				error: {
+					code: "git/not_found",
+					message: `Unknown git RPC endpoint: ${endpoint}`,
+					details: {}
+				}
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: {
+					code: "git/error",
+					message: error instanceof Error ? error.message : String(error),
+					details: {}
+				}
+			};
+		}
+	});
+	registerGitTool(ctx, resolveTargetDir);
+}
+export { apply, inject, name };