@openspecui/server 2.1.7 → 2.2.0

package/dist/index.mjs

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 import { WebSocketServer } from "ws";
 import { EventEmitter } from "node:events";
 import { execFile } from "node:child_process";
-import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import * as pty from "@lydell/node-pty";
 import { EventEmitter as EventEmitter$1 } from "events";
@@ -153,7 +153,7 @@ function selectRecentDashboardItems(items, limit = DASHBOARD_RECENT_LIST_LIMIT)
 }
 
 //#endregion
-//#region src/dashboard-git-snapshot.ts
+//#region src/git-shared.ts
 const execFileAsync$1 = promisify(execFile);
 const EMPTY_DIFF = {
 	files: 0,
@@ -186,6 +186,14 @@ async function defaultReadPathTimestampMs(absolutePath) {
 		return null;
 	}
 }
+async function pathExists(absolutePath) {
+	try {
+		await stat(absolutePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
 function parseShortStat(output) {
 	const files = Number(/(\d+)\s+files? changed/.exec(output)?.[1] ?? 0);
 	const insertions = Number(/(\d+)\s+insertions?\(\+\)/.exec(output)?.[1] ?? 0);
@@ -196,33 +204,48 @@ function parseShortStat(output) {
 		deletions: Number.isFinite(deletions) ? deletions : 0
 	};
 }
-function parseNumStat(output) {
-	let files = 0;
-	let insertions = 0;
-	let deletions = 0;
-	for (const line of output.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		const [addRaw, deleteRaw] = trimmed.split("	");
-		if (!addRaw || !deleteRaw) continue;
-		files += 1;
-		if (addRaw !== "-") insertions += Number(addRaw) || 0;
-		if (deleteRaw !== "-") deletions += Number(deleteRaw) || 0;
-	}
-	return {
-		files,
-		insertions,
-		deletions
-	};
-}
 function normalizeGitPath(path) {
 	return path.replace(/\\/g, "/").replace(/^\.\//, "");
 }
+function extractGitPathVariants(rawPath) {
+	const trimmed = rawPath.trim();
+	if (!trimmed) return [];
+	const normalizedRaw = normalizeGitPath(trimmed);
+	const braceRenameMatch = /^(.*?)\{(.*?) => (.*?)\}(.*)$/.exec(trimmed);
+	if (braceRenameMatch) {
+		const [, prefix = "", left = "", right = "", suffix = ""] = braceRenameMatch;
+		const variants = /* @__PURE__ */ new Set();
+		variants.add(normalizeGitPath(`${prefix}${left}${suffix}`));
+		variants.add(normalizeGitPath(`${prefix}${right}${suffix}`));
+		return [...variants];
+	}
+	const renameParts = trimmed.split(" => ");
+	if (renameParts.length === 2) {
+		const [left = "", right = ""] = renameParts;
+		const variants = /* @__PURE__ */ new Set();
+		variants.add(normalizeGitPath(left));
+		variants.add(normalizeGitPath(right));
+		return [...variants];
+	}
+	return [normalizedRaw];
+}
 function relativePath(fromDir, target) {
 	const rel = relative(fromDir, target);
 	if (!rel || rel.length === 0) return ".";
 	return rel;
 }
+async function canonicalGitPath(path) {
+	const resolved = resolve(path);
+	try {
+		return await realpath(resolved);
+	} catch {
+		return resolved;
+	}
+}
+async function sameGitPath(left, right) {
+	const [canonicalLeft, canonicalRight] = await Promise.all([canonicalGitPath(left), canonicalGitPath(right)]);
+	return canonicalLeft === canonicalRight;
+}
 function parseBranchName(branchRef, detached) {
 	if (detached) return "(detached)";
 	if (!branchRef) return "(unknown)";
@@ -251,10 +274,7 @@ function parseWorktreeList(porcelain) {
 			current.branchRef = line.slice(7).trim();
 			continue;
 		}
-		if (line === "detached") {
-			current.detached = true;
-			continue;
-		}
+		if (line === "detached") current.detached = true;
 	}
 	flush();
 	return entries;
@@ -263,16 +283,17 @@ function parseRelatedChanges(paths) {
 	const related = /* @__PURE__ */ new Set();
 	for (const path of paths) {
 		const normalized = normalizeGitPath(path);
+		if (normalized.includes("{") || normalized.includes("=>")) continue;
+		const archiveMatch = /^openspec\/changes\/archive\/([^/]+)\//.exec(normalized);
+		if (archiveMatch?.[1]) {
+			related.add(archiveMatch[1].replace(/^\d{4}-\d{2}-\d{2}-/, ""));
+			continue;
+		}
 		const activeMatch = /^openspec\/changes\/([^/]+)\//.exec(normalized);
 		if (activeMatch?.[1]) {
 			related.add(activeMatch[1]);
 			continue;
 		}
-		const archiveMatch = /^openspec\/changes\/archive\/([^/]+)\//.exec(normalized);
-		if (archiveMatch?.[1]) {
-			const fullName = archiveMatch[1];
-			related.add(fullName.replace(/^\d{4}-\d{2}-\d{2}-/, ""));
-		}
 	}
 	return [...related].sort((a, b) => a.localeCompare(b));
 }
@@ -294,41 +315,112 @@ async function resolveDefaultBranch(projectDir, runGit) {
 	if (localHead.ok && localRef && localRef !== "HEAD") return localRef;
 	return "main";
 }
-async function collectCommitEntries(options) {
-	const { worktreePath, defaultBranch, maxCommitEntries, runGit, readPathTimestampMs } = options;
-	const commitEntries = [];
+async function listGitWorktrees(projectDir, runGit) {
+	const resolvedProjectDir = resolve(projectDir);
+	const worktreeResult = await runGit(resolvedProjectDir, [
+		"worktree",
+		"list",
+		"--porcelain"
+	]);
+	const parsed = worktreeResult.ok ? parseWorktreeList(worktreeResult.stdout) : [];
+	if (parsed.length > 0) return parsed;
+	return [{
+		path: resolvedProjectDir,
+		branchRef: null,
+		detached: false
+	}];
+}
+
+//#endregion
+//#region src/git-entry-summary.ts
+function createEmptyCommitRecord(hash, committedAt, title) {
+	return {
+		hash,
+		committedAt,
+		title,
+		diff: { ...EMPTY_DIFF },
+		changedPaths: []
+	};
+}
+function parseGitLogNumstatRecords(stdout) {
+	const records = [];
+	for (const block of stdout.split("")) {
+		const trimmedBlock = block.trim();
+		if (!trimmedBlock) continue;
+		const lines = trimmedBlock.split("\n");
+		const header = lines.shift()?.trim();
+		if (!header) continue;
+		const [hash, committedAtRaw = "0", title = ""] = header.split("");
+		if (!hash) continue;
+		const committedAtSeconds = Number(committedAtRaw);
+		const record = createEmptyCommitRecord(hash, Number.isFinite(committedAtSeconds) && committedAtSeconds > 0 ? committedAtSeconds * 1e3 : 0, title.trim() || hash.slice(0, 7));
+		for (const line of lines) {
+			const trimmedLine = line.trim();
+			if (!trimmedLine) continue;
+			const parts = trimmedLine.split("	");
+			if (parts.length < 3) continue;
+			const [insertionsRaw = "0", deletionsRaw = "0", ...pathParts] = parts;
+			const rawPath = pathParts.join("	").trim();
+			if (!rawPath) continue;
+			record.diff.files += 1;
+			if (insertionsRaw !== "-") record.diff.insertions += Number(insertionsRaw) || 0;
+			if (deletionsRaw !== "-") record.diff.deletions += Number(deletionsRaw) || 0;
+			record.changedPaths.push(...extractGitPathVariants(rawPath));
+		}
+		records.push(record);
+	}
+	return records;
+}
+async function listGitCommitEntriesPage(options) {
+	const { worktreePath, defaultBranch, offset, limit, runGit } = options;
 	const commits = await runGit(worktreePath, [
 		"log",
-		"--format=%H%x1f%ct%x1f%s",
-		`-n${maxCommitEntries}`,
+		"--format=%x1e%H%x1f%ct%x1f%s",
+		"--numstat",
+		`--skip=${offset}`,
+		`-n${limit + 1}`,
 		`${defaultBranch}..HEAD`
 	]);
-	if (commits.ok) for (const line of commits.stdout.split("\n")) {
-		if (!line.trim()) continue;
-		const [hash, committedAtRaw = "0", title = ""] = line.split("");
-		if (!hash) continue;
-		const diffResult = await runGit(worktreePath, [
-			"show",
-			"--numstat",
-			"--format=",
-			hash
-		]);
-		const changedFiles = (await runGit(worktreePath, [
-			"show",
-			"--name-only",
-			"--format=",
-			hash
-		])).stdout.split("\n").map((item) => item.trim()).filter((item) => item.length > 0);
-		const committedAt = Number(committedAtRaw) * 1e3;
-		commitEntries.push({
+	if (!commits.ok) return {
+		items: [],
+		nextCursor: null
+	};
+	const records = parseGitLogNumstatRecords(commits.stdout);
+	return {
+		items: records.slice(0, limit).map((record) => ({
 			type: "commit",
-			hash,
-			title: title.trim() || hash.slice(0, 7),
-			committedAt: Number.isFinite(committedAt) && committedAt > 0 ? committedAt : 0,
-			relatedChanges: parseRelatedChanges(changedFiles),
-			diff: diffResult.ok ? parseNumStat(diffResult.stdout) : EMPTY_DIFF
-		});
-	}
+			hash: record.hash,
+			title: record.title,
+			committedAt: record.committedAt,
+			relatedChanges: parseRelatedChanges(record.changedPaths),
+			diff: record.diff
+		})),
+		nextCursor: records.length > limit ? String(offset + limit) : null
+	};
+}
+async function readGitCommitEntryByHash(options) {
+	const { worktreePath, hash, runGit } = options;
+	const result = await runGit(worktreePath, [
+		"show",
+		"--numstat",
+		"--format=%x1e%H%x1f%ct%x1f%s",
+		hash
+	]);
+	if (!result.ok) return null;
+	const record = parseGitLogNumstatRecords(result.stdout)[0];
+	if (!record) return null;
+	return {
+		type: "commit",
+		hash: record.hash,
+		title: record.title,
+		committedAt: record.committedAt,
+		relatedChanges: parseRelatedChanges(record.changedPaths),
+		diff: record.diff
+	};
+}
+async function collectUncommittedEntrySummary(options) {
+	const { worktreePath, runGit } = options;
+	const readPathTimestampMs = options.readPathTimestampMs ?? defaultReadPathTimestampMs;
 	const trackedResult = await runGit(worktreePath, [
 		"diff",
 		"--numstat",
@@ -346,32 +438,57 @@ async function collectCommitEntries(options) {
 	]);
 	const trackedFiles = trackedFilesResult.stdout.split("\n").map((item) => item.trim()).filter((item) => item.length > 0);
 	const untrackedFiles = untrackedResult.stdout.split("\n").map((item) => item.trim()).filter((item) => item.length > 0);
+	const trackedDiff = parseGitLogNumstatRecords(`\u001ehead\u001f0\u001fUncommitted\n${trackedResult.stdout}`)[0]?.diff ?? EMPTY_DIFF;
 	const allUncommittedFiles = new Set([...trackedFiles, ...untrackedFiles]);
-	const trackedDiff = trackedResult.ok ? parseNumStat(trackedResult.stdout) : EMPTY_DIFF;
-	const updatedAt = (await Promise.all([...allUncommittedFiles].map((path) => readPathTimestampMs(resolve(worktreePath, path))))).reduce((latest, current) => {
-		if (!current || !Number.isFinite(current) || current <= 0) return latest;
-		return latest === null || current > latest ? current : latest;
-	}, null) ?? null;
-	commitEntries.sort((left, right) => {
-		if (left.type !== "commit" || right.type !== "commit") return 0;
-		return right.committedAt - left.committedAt;
-	});
-	return [{
+	return {
 		type: "uncommitted",
 		title: "Uncommitted",
-		updatedAt,
+		updatedAt: (await Promise.all([...allUncommittedFiles].map((path) => readPathTimestampMs(resolve(worktreePath, path))))).reduce((latest, current) => {
+			if (!current || !Number.isFinite(current) || current <= 0) return latest;
+			return latest === null || current > latest ? current : latest;
+		}, null) ?? null,
 		relatedChanges: parseRelatedChanges([...allUncommittedFiles]),
 		diff: {
 			files: allUncommittedFiles.size,
 			insertions: trackedDiff.insertions,
 			deletions: trackedDiff.deletions
 		}
-	}, ...commitEntries];
+	};
+}
+async function listRecentGitEntries(options) {
+	const { worktreePath, defaultBranch, maxCommitEntries, runGit, readPathTimestampMs } = options;
+	const [uncommitted, commitsPage] = await Promise.all([collectUncommittedEntrySummary({
+		worktreePath,
+		runGit,
+		readPathTimestampMs
+	}), listGitCommitEntriesPage({
+		worktreePath,
+		defaultBranch,
+		offset: 0,
+		limit: maxCommitEntries,
+		runGit
+	})]);
+	return [uncommitted, ...commitsPage.items];
+}
+
+//#endregion
+//#region src/dashboard-git-snapshot.ts
+async function collectCommitEntries(options) {
+	const { worktreePath, defaultBranch, maxCommitEntries, runGit, readPathTimestampMs } = options;
+	return listRecentGitEntries({
+		worktreePath,
+		defaultBranch,
+		maxCommitEntries,
+		runGit,
+		readPathTimestampMs
+	});
 }
 async function collectWorktree(options) {
 	const { projectDir, worktree, defaultBranch, runGit, maxCommitEntries, readPathTimestampMs } = options;
 	const worktreePath = resolve(worktree.path);
 	const resolvedProjectDir = resolve(projectDir);
+	const isCurrent = await sameGitPath(worktreePath, resolvedProjectDir);
+	const pathAvailable = await pathExists(worktreePath);
 	const aheadBehindResult = await runGit(worktreePath, [
 		"rev-list",
 		"--left-right",
@@ -401,9 +518,10 @@ async function collectWorktree(options) {
 	return {
 		path: worktreePath,
 		relativePath: relativePath(resolvedProjectDir, worktreePath),
+		pathAvailable,
 		branchName: parseBranchName(worktree.branchRef, worktree.detached),
 		detached: worktree.detached,
-		isCurrent: resolvedProjectDir === worktreePath,
+		isCurrent,
 		ahead,
 		behind,
 		diff,
@@ -414,14 +532,13 @@ async function removeDetachedDashboardGitWorktree(options) {
 	const runGit = options.runGit ?? defaultRunGit;
 	const resolvedProjectDir = resolve(options.projectDir);
 	const resolvedTargetPath = resolve(options.targetPath);
-	if (resolvedTargetPath === resolvedProjectDir) throw new Error("Cannot remove the current worktree.");
-	const worktreeResult = await runGit(resolvedProjectDir, [
-		"worktree",
-		"list",
-		"--porcelain"
-	]);
-	if (!worktreeResult.ok) throw new Error("Failed to inspect git worktrees.");
-	const matched = parseWorktreeList(worktreeResult.stdout).find((worktree) => resolve(worktree.path) === resolvedTargetPath);
+	if (await sameGitPath(resolvedTargetPath, resolvedProjectDir)) throw new Error("Cannot remove the current worktree.");
+	const worktrees = await listGitWorktrees(resolvedProjectDir, runGit);
+	let matched;
+	for (const worktree of worktrees) if (await sameGitPath(worktree.path, resolvedTargetPath)) {
+		matched = worktree;
+		break;
+	}
 	if (!matched) throw new Error("Worktree not found.");
 	if (!matched.detached) throw new Error("Only detached worktrees can be removed from Dashboard.");
 	if (!(await runGit(resolvedProjectDir, [
@@ -437,17 +554,7 @@ async function buildDashboardGitSnapshot(options) {
 	const readPathTimestampMs = options.readPathTimestampMs ?? defaultReadPathTimestampMs;
 	const resolvedProjectDir = resolve(options.projectDir);
 	const defaultBranch = await resolveDefaultBranch(resolvedProjectDir, runGit);
-	const worktreeResult = await runGit(resolvedProjectDir, [
-		"worktree",
-		"list",
-		"--porcelain"
-	]);
-	const parsed = worktreeResult.ok ? parseWorktreeList(worktreeResult.stdout) : [];
-	const baseWorktrees = parsed.length > 0 ? parsed : [{
-		path: resolvedProjectDir,
-		branchRef: null,
-		detached: false
-	}];
+	const baseWorktrees = await listGitWorktrees(resolvedProjectDir, runGit);
 	const worktrees = await Promise.all(baseWorktrees.map((worktree) => collectWorktree({
 		projectDir: resolvedProjectDir,
 		worktree,
@@ -1247,6 +1354,457 @@ function createCliStreamObservable(startStream) {
 	});
 }
 
+//#endregion
+//#region src/git-panel-cache.ts
+const gitPanelCaches = {
+	overview: /* @__PURE__ */ new Map(),
+	entries: /* @__PURE__ */ new Map(),
+	shell: /* @__PURE__ */ new Map(),
+	patch: /* @__PURE__ */ new Map()
+};
+function buildCacheKey(projectDir, key) {
+	return `${resolve(projectDir)}::${key}`;
+}
+function getCacheVersion() {
+	return getDashboardGitTaskStatus().lastFinishedAt ?? 0;
+}
+async function getCachedGitPanelValue(scope, projectDir, key, load) {
+	const cache = gitPanelCaches[scope];
+	const cacheKey = buildCacheKey(projectDir, key);
+	const version = getCacheVersion();
+	const hit = cache.get(cacheKey);
+	if (hit && hit.version === version) return hit.value;
+	const value = await load();
+	cache.set(cacheKey, {
+		version,
+		value
+	});
+	return value;
+}
+
+//#endregion
+//#region src/git-panel-data.ts
+const DEFAULT_ENTRY_PAGE_SIZE = 50;
+const MAX_ENTRY_PAGE_SIZE = 100;
+const MAX_PATCH_BYTES = 2e5;
+const MAX_SYNTHETIC_TEXT_BYTES = 2e5;
+function clampEntryLimit(limit) {
+	if (!Number.isFinite(limit)) return DEFAULT_ENTRY_PAGE_SIZE;
+	return Math.max(1, Math.min(MAX_ENTRY_PAGE_SIZE, Math.trunc(limit ?? DEFAULT_ENTRY_PAGE_SIZE)));
+}
+function parseCursor(cursor) {
+	const value = Number(cursor);
+	if (!Number.isFinite(value) || value < 0) return 0;
+	return Math.trunc(value);
+}
+function createGitFileId(path, previousPath) {
+	return JSON.stringify([previousPath ?? null, path]);
+}
+function parseGitNameStatus(stdout) {
+	const entries = [];
+	for (const line of stdout.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const parts = trimmed.split("	");
+		const normalized = (parts[0] ?? "")[0] ?? "";
+		if (!normalized) continue;
+		if ((normalized === "R" || normalized === "C") && parts.length >= 3) {
+			entries.push({
+				previousPath: parts[1] ?? null,
+				path: parts[2] ?? "",
+				changeType: normalized === "R" ? "renamed" : "copied"
+			});
+			continue;
+		}
+		if (parts.length < 2) continue;
+		entries.push({
+			previousPath: null,
+			path: parts[1] ?? "",
+			changeType: normalized === "A" ? "added" : normalized === "M" ? "modified" : normalized === "D" ? "deleted" : normalized === "T" ? "typechanged" : normalized === "U" ? "unmerged" : "unknown"
+		});
+	}
+	return entries;
+}
+function parseNumStatMap(stdout) {
+	const diffByPath = /* @__PURE__ */ new Map();
+	for (const line of stdout.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const parts = trimmed.split("	");
+		if (parts.length < 3) continue;
+		const [insertionsRaw = "0", deletionsRaw = "0", ...pathParts] = parts;
+		const rawPath = pathParts.join("	").trim();
+		const diff = {
+			files: 1,
+			insertions: insertionsRaw === "-" ? 0 : Number(insertionsRaw) || 0,
+			deletions: deletionsRaw === "-" ? 0 : Number(deletionsRaw) || 0
+		};
+		for (const path of extractGitPathVariants(rawPath)) diffByPath.set(path, diff);
+	}
+	return diffByPath;
+}
+function resolveTrackedDiff(diffByPath, status) {
+	return diffByPath.get(status.path) ?? (status.previousPath ? diffByPath.get(status.previousPath) : void 0) ?? {
+		files: 1,
+		insertions: 0,
+		deletions: 0
+	};
+}
+function readyFileDiff(diff) {
+	return {
+		state: "ready",
+		...diff
+	};
+}
+function loadingFileDiff(files = 1) {
+	return {
+		state: "loading",
+		files
+	};
+}
+function unavailableFileDiff(files = 1) {
+	return {
+		state: "unavailable",
+		files
+	};
+}
+function buildTrackedFileSummaries(statuses, numStatOutput) {
+	const diffByPath = parseNumStatMap(numStatOutput);
+	return statuses.map((status) => ({
+		fileId: createGitFileId(status.path, status.previousPath),
+		source: "tracked",
+		path: status.path,
+		displayPath: status.previousPath ? `${status.previousPath} -> ${status.path}` : status.path,
+		previousPath: status.previousPath,
+		changeType: status.changeType,
+		diff: readyFileDiff(resolveTrackedDiff(diffByPath, status))
+	})).sort((left, right) => left.path.localeCompare(right.path));
+}
+function buildUntrackedFileSummary(path) {
+	return {
+		fileId: createGitFileId(path, null),
+		source: "untracked",
+		path,
+		displayPath: path,
+		previousPath: null,
+		changeType: "added",
+		diff: loadingFileDiff()
+	};
+}
+async function collectWorktreeSummary(options) {
+	const { projectDir, worktree, defaultBranch, runGit } = options;
+	const worktreePath = resolve(worktree.path);
+	const resolvedProjectDir = resolve(projectDir);
+	const isCurrent = await sameGitPath(worktreePath, resolvedProjectDir);
+	const pathAvailable = await pathExists(worktreePath);
+	const aheadBehindResult = await runGit(worktreePath, [
+		"rev-list",
+		"--left-right",
+		"--count",
+		`${defaultBranch}...HEAD`
+	]);
+	let ahead = 0;
+	let behind = 0;
+	if (aheadBehindResult.ok) {
+		const [behindRaw, aheadRaw] = aheadBehindResult.stdout.trim().split(/\s+/);
+		ahead = Number(aheadRaw) || 0;
+		behind = Number(behindRaw) || 0;
+	}
+	const diffResult = await runGit(worktreePath, [
+		"diff",
+		"--shortstat",
+		`${defaultBranch}...HEAD`
+	]);
+	const diff = diffResult.ok ? parseShortStat(diffResult.stdout) : EMPTY_DIFF;
+	return {
+		path: worktreePath,
+		relativePath: relativePath(resolvedProjectDir, worktreePath),
+		pathAvailable,
+		branchName: parseBranchName(worktree.branchRef, worktree.detached),
+		detached: worktree.detached,
+		isCurrent,
+		ahead,
+		behind,
+		diff
+	};
+}
+function normalizePatchState(patch) {
+	const trimmed = patch.trimEnd();
+	if (!trimmed) return {
+		state: "unavailable",
+		patch: null
+	};
+	if (/^GIT binary patch$/m.test(trimmed) || /^Binary files .* differ$/m.test(trimmed)) return {
+		state: "binary",
+		patch: null
+	};
+	if (Buffer.byteLength(trimmed, "utf8") > MAX_PATCH_BYTES) return {
+		state: "too-large",
+		patch: null
+	};
+	return {
+		state: "available",
+		patch: trimmed
+	};
+}
+function splitPatchLines(text) {
+	if (!text) return [];
+	const lines = text.replace(/\r\n/g, "\n").split("\n");
+	if (lines.at(-1) === "") lines.pop();
+	return lines;
+}
+async function buildTrackedPatchFile(options) {
+	const { worktreePath, file, runGit, selector } = options;
+	const patchResult = await runGit(worktreePath, selector.type === "commit" ? [
+		"show",
+		"--patch",
+		"--find-renames",
+		"--format=",
+		selector.hash,
+		"--",
+		file.path
+	] : [
+		"diff",
+		"--patch",
+		"--find-renames",
+		"HEAD",
+		"--",
+		file.path
+	]);
+	const normalized = normalizePatchState(patchResult.stdout);
+	return {
+		...file,
+		patch: normalized.patch,
+		state: patchResult.ok ? normalized.state : "unavailable"
+	};
+}
+async function buildUntrackedPatchFile(worktreePath, file) {
+	try {
+		const buffer = await readFile(resolve(worktreePath, file.path));
+		if (buffer.byteLength > MAX_SYNTHETIC_TEXT_BYTES) return {
+			...file,
+			diff: unavailableFileDiff(),
+			patch: null,
+			state: "too-large"
+		};
+		if (buffer.includes(0)) return {
+			...file,
+			diff: unavailableFileDiff(),
+			patch: null,
+			state: "binary"
+		};
+		const lines = splitPatchLines(buffer.toString("utf8"));
+		const hunkHeader = lines.length > 0 ? `@@ -0,0 +1,${lines.length} @@` : null;
+		const body = lines.map((line) => `+${line}`);
+		const patch = [
+			`diff --git a/${file.path} b/${file.path}`,
+			"new file mode 100644",
+			"--- /dev/null",
+			`+++ b/${file.path}`,
+			...hunkHeader ? [hunkHeader] : [],
+			...body
+		].join("\n");
+		return {
+			...file,
+			diff: readyFileDiff({
+				files: 1,
+				insertions: lines.length,
+				deletions: 0
+			}),
+			patch: patch.trimEnd(),
+			state: "available"
+		};
+	} catch {
+		return {
+			...file,
+			diff: unavailableFileDiff(),
+			patch: null,
+			state: "unavailable"
+		};
+	}
+}
+async function buildCommitShell(options) {
+	const { worktreePath, hash, runGit } = options;
+	const [entry, nameStatusResult, numStatResult] = await Promise.all([
+		readGitCommitEntryByHash({
+			worktreePath,
+			hash,
+			runGit
+		}),
+		runGit(worktreePath, [
+			"show",
+			"--name-status",
+			"--find-renames",
+			"--format=",
+			hash
+		]),
+		runGit(worktreePath, [
+			"show",
+			"--numstat",
+			"--format=",
+			hash
+		])
+	]);
+	if (!entry) return {
+		entry: null,
+		files: []
+	};
+	return {
+		entry,
+		files: buildTrackedFileSummaries(nameStatusResult.ok ? parseGitNameStatus(nameStatusResult.stdout) : [], numStatResult.stdout)
+	};
+}
+async function buildUncommittedShell(options) {
+	const { worktreePath, runGit, readPathTimestampMs } = options;
+	const [entry, trackedStatusResult, trackedNumStatResult, untrackedResult] = await Promise.all([
+		collectUncommittedEntrySummary({
+			worktreePath,
+			runGit,
+			readPathTimestampMs
+		}),
+		runGit(worktreePath, [
+			"diff",
+			"--name-status",
+			"--find-renames",
+			"HEAD"
+		]),
+		runGit(worktreePath, [
+			"diff",
+			"--numstat",
+			"HEAD"
+		]),
+		runGit(worktreePath, [
+			"ls-files",
+			"--others",
+			"--exclude-standard"
+		])
+	]);
+	const trackedFiles = buildTrackedFileSummaries(trackedStatusResult.ok ? parseGitNameStatus(trackedStatusResult.stdout) : [], trackedNumStatResult.stdout);
+	const untrackedFiles = untrackedResult.stdout.split("\n").map((item) => item.trim()).filter((item) => item.length > 0).map((path) => buildUntrackedFileSummary(path));
+	return {
+		entry,
+		files: [...trackedFiles, ...untrackedFiles].sort((left, right) => left.path.localeCompare(right.path))
+	};
+}
+async function loadGitEntryShell(options) {
+	const runGit = options.runGit ?? defaultRunGit;
+	const readPathTimestampMs = options.readPathTimestampMs ?? defaultReadPathTimestampMs;
+	const resolvedProjectDir = resolve(options.projectDir);
+	if (options.selector.type === "uncommitted") return buildUncommittedShell({
+		worktreePath: resolvedProjectDir,
+		runGit,
+		readPathTimestampMs
+	});
+	return buildCommitShell({
+		worktreePath: resolvedProjectDir,
+		hash: options.selector.hash,
+		runGit
+	});
+}
+async function buildGitWorktreeOverview(options) {
+	const resolvedProjectDir = resolve(options.projectDir);
+	return getCachedGitPanelValue("overview", resolvedProjectDir, "overview", async () => {
+		const runGit = options.runGit ?? defaultRunGit;
+		const defaultBranch = await resolveDefaultBranch(resolvedProjectDir, runGit);
+		const worktrees = await listGitWorktrees(resolvedProjectDir, runGit);
+		const summaries = await Promise.all(worktrees.map((worktree) => collectWorktreeSummary({
+			projectDir: resolvedProjectDir,
+			worktree,
+			defaultBranch,
+			runGit
+		})));
+		summaries.sort((left, right) => {
+			if (left.isCurrent !== right.isCurrent) return left.isCurrent ? -1 : 1;
+			return left.branchName.localeCompare(right.branchName);
+		});
+		return {
+			defaultBranch,
+			currentWorktree: summaries.find((worktree) => worktree.isCurrent) ?? null,
+			otherWorktrees: summaries.filter((worktree) => !worktree.isCurrent)
+		};
+	});
+}
+async function listCurrentWorktreeGitEntries(options) {
+	const resolvedProjectDir = resolve(options.projectDir);
+	const limit = clampEntryLimit(options.limit);
+	const offset = parseCursor(options.cursor);
+	return getCachedGitPanelValue("entries", resolvedProjectDir, `entries:${offset}:${limit}`, async () => {
+		const runGit = options.runGit ?? defaultRunGit;
+		const readPathTimestampMs = options.readPathTimestampMs ?? defaultReadPathTimestampMs;
+		const defaultBranch = await resolveDefaultBranch(resolvedProjectDir, runGit);
+		const uncommitted = await collectUncommittedEntrySummary({
+			worktreePath: resolvedProjectDir,
+			runGit,
+			readPathTimestampMs
+		});
+		const includeUncommitted = offset === 0 && uncommitted.diff.files > 0;
+		const commitLimit = includeUncommitted ? Math.max(0, limit - 1) : limit;
+		const commitsPage = commitLimit > 0 ? await listGitCommitEntriesPage({
+			worktreePath: resolvedProjectDir,
+			defaultBranch,
+			offset,
+			limit: commitLimit,
+			runGit
+		}) : {
+			items: [],
+			nextCursor: null
+		};
+		return {
+			items: includeUncommitted ? [uncommitted, ...commitsPage.items] : commitsPage.items,
+			nextCursor: commitsPage.nextCursor
+		};
+	});
+}
+async function getCurrentWorktreeGitEntryShell(options) {
+	const resolvedProjectDir = resolve(options.projectDir);
+	return getCachedGitPanelValue("shell", resolvedProjectDir, options.selector.type === "commit" ? `commit:${options.selector.hash}` : "uncommitted", () => loadGitEntryShell({
+		...options,
+		projectDir: resolvedProjectDir
+	}));
+}
+async function getCurrentWorktreeGitEntryPatch(options) {
+	const resolvedProjectDir = resolve(options.projectDir);
+	return getCachedGitPanelValue("patch", resolvedProjectDir, `${options.selector.type === "commit" ? `commit:${options.selector.hash}` : "uncommitted"}:${options.fileId}`, async () => {
+		const runGit = options.runGit ?? defaultRunGit;
+		const shell = await getCurrentWorktreeGitEntryShell({
+			...options,
+			projectDir: resolvedProjectDir
+		});
+		const file = shell.files.find((candidate) => candidate.fileId === options.fileId) ?? null;
+		if (!shell.entry || !file) return {
+			entry: shell.entry,
+			file: null
+		};
+		const patch = file.source === "untracked" ? await buildUntrackedPatchFile(resolvedProjectDir, file) : await buildTrackedPatchFile({
+			worktreePath: resolvedProjectDir,
+			file,
+			runGit,
+			selector: options.selector
+		});
+		return {
+			entry: shell.entry,
+			file: patch
+		};
+	});
+}
+async function getCurrentWorktreeGitEntryDetail(options) {
+	const shell = await getCurrentWorktreeGitEntryShell(options);
+	if (!shell.entry) return {
+		entry: null,
+		files: []
+	};
+	const patches = await Promise.all(shell.files.map(async (file) => {
+		return (await getCurrentWorktreeGitEntryPatch({
+			...options,
+			fileId: file.fileId
+		})).file;
+	}));
+	return {
+		entry: shell.entry,
+		files: patches.filter((file) => file !== null)
+	};
+}
+
 //#endregion
 //#region src/reactive-kv.ts
 /**
@@ -1373,6 +1931,10 @@ const OPSX_CORE_PROFILE_WORKFLOWS = [
 	"apply",
 	"archive"
 ];
+const gitEntrySelectorSchema = z.discriminatedUnion("type", [z.object({ type: z.literal("uncommitted") }), z.object({
+	type: z.literal("commit"),
+	hash: z.string().min(1)
+})]);
 function requireChangeId(changeId) {
 	if (!changeId) throw new Error("change is required");
 	return changeId;
@@ -2317,11 +2879,63 @@ const dashboardRouter = router({
 		});
 	})
 });
+const gitRouter = router({
+	overview: publicProcedure.query(async ({ ctx }) => {
+		return buildGitWorktreeOverview({ projectDir: ctx.projectDir });
+	}),
+	listEntries: publicProcedure.input(z.object({
+		cursor: z.string().optional(),
+		limit: z.number().int().min(1).max(100).optional()
+	}).optional()).query(async ({ ctx, input }) => {
+		return listCurrentWorktreeGitEntries({
+			projectDir: ctx.projectDir,
+			cursor: input?.cursor,
+			limit: input?.limit
+		});
+	}),
+	getEntryDetail: publicProcedure.input(z.object({ selector: gitEntrySelectorSchema })).query(async ({ ctx, input }) => {
+		return getCurrentWorktreeGitEntryDetail({
+			projectDir: ctx.projectDir,
+			selector: input.selector
+		});
+	}),
+	getEntryShell: publicProcedure.input(z.object({ selector: gitEntrySelectorSchema })).query(async ({ ctx, input }) => {
+		return getCurrentWorktreeGitEntryShell({
+			projectDir: ctx.projectDir,
+			selector: input.selector
+		});
+	}),
+	getEntryPatch: publicProcedure.input(z.object({
+		selector: gitEntrySelectorSchema,
+		fileId: z.string().min(1)
+	})).query(async ({ ctx, input }) => {
+		return getCurrentWorktreeGitEntryPatch({
+			projectDir: ctx.projectDir,
+			selector: input.selector,
+			fileId: input.fileId
+		});
+	}),
+	switchWorktree: publicProcedure.input(z.object({ path: z.string().min(1) })).mutation(async ({ ctx, input }) => {
+		if (!ctx.gitWorktreeHandoff) throw new Error("Worktree handoff is unavailable in this runtime.");
+		const overview = await buildGitWorktreeOverview({ projectDir: ctx.projectDir });
+		const resolvedInputPath = resolve(input.path);
+		let target = null;
+		if (overview.currentWorktree && await sameGitPath(overview.currentWorktree.path, resolvedInputPath)) target = overview.currentWorktree;
+		else for (const worktree of overview.otherWorktrees) if (await sameGitPath(worktree.path, resolvedInputPath)) {
+			target = worktree;
+			break;
+		}
+		if (!target) throw new Error("Worktree not found.");
+		if (!target.pathAvailable) throw new Error("Worktree path is no longer available. Remove the stale worktree entry first.");
+		return ctx.gitWorktreeHandoff.ensureWorktreeServer({ targetPath: target.path });
+	})
+});
 /**
 * Main app router
 */
 const appRouter = router({
 	dashboard: dashboardRouter,
+	git: gitRouter,
 	spec: specRouter,
 	change: changeRouter,
 	archive: archiveRouter,
@@ -2535,6 +3149,7 @@ function createServer(config) {
 				kernel,
 				searchService,
 				dashboardOverviewService,
+				gitWorktreeHandoff: config.gitWorktreeHandoff,
 				watcher,
 				projectDir: config.projectDir
 			})
@@ -2547,6 +3162,7 @@ function createServer(config) {
 		kernel,
 		searchService,
 		dashboardOverviewService,
+		gitWorktreeHandoff: config.gitWorktreeHandoff,
 		watcher,
 		projectDir: config.projectDir
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openspecui/server",
-  "version": "2.1.7",
+  "version": "2.2.0",
   "type": "module",
   "main": "dist/index.mjs",
   "exports": {