@marktrue/dsh-mobile-remote 3.2.1-rc.1-app → 3.2.1-rc.1

package/lib/endpoint-registry.js

@@ -0,0 +1,165 @@
+// 端点登记表（ADR 0019「能力登记强制化」；评审 #32 note 1286 的 W2）。
+//
+// 三条判据里「能力能不能用」看的是**能力声明**；而声明要成立，前提是"新增端点时必须有人
+// 登记它"。此前这件事只写在 CONTRIBUTING 的文字要求里，没有机制兜底——于是必然漏。
+//
+// 这里把登记变成**可被测试检出**的东西：
+//   - 从 `lib/index.js` 抽取所有正向分派（`rest === "..."`、`new Set([...]).has(rest)`），
+//     与登记表**双向**比对：漏登记、陈旧登记、**方法不符**都会失败；
+//   - 抽取正则容忍引号与空白差异（`rest === '/x'`、`rest==="/x"` 同样会被抓到）；
+//   - 每条登记项都必须显式写出 `capability`（能力键或 `null`）；写了键就必须真的在
+//     bootstrap 的 capabilities 里声明过，否则失败。
+//
+// 已知边界（不假装更强）：`methods` 由源码按分派段落推导，是**契约快照**而非运行期保证；
+// 端点自身仍靠 `requireGet`/`method` 检查在运行时兜底。
+
+/** 抽取正向分派所用的源码文件（相对仓库根）。 */
+export const ENDPOINT_DISPATCH_SOURCE = "lib/index.js";
+
+/** 从源码抽取"正向分派"及其方法（按分派段落判定，不看固定窗口）。 */
+export function extractEndpointDetails(source) {
+	const lines = source.split("\n");
+	const marks = [];
+	lines.forEach((line, index) => {
+		for (const m of line.matchAll(/rest\s*===\s*['"]([^'"]+)['"]/g)) marks.push({ index, path: m[1] });
+		for (const group of line.matchAll(/new Set\(\[([^\]]+)\]\)\s*\.has\(rest\)/g)) {
+			for (const m of group[1].matchAll(/['"]([^'"]+)['"]/g)) marks.push({ index, path: m[1] });
+		}
+	});
+	marks.sort((a, b) => a.index - b.index);
+	const markLines = [...new Set(marks.map((m) => m.index))].sort((a, b) => a - b);
+	const out = new Map();
+	for (const { index, path } of marks) {
+		if (out.has(path)) continue;
+		const next = markLines.find((l) => l > index);
+		const segment = lines.slice(index, next ?? Math.min(lines.length, index + 400)).join("\n");
+		let methods = "GET/POST";
+		if (/requireGet\(method,\s*res\)/.test(segment) || /method\s*!==\s*['"]GET['"]/.test(segment)) methods = "GET";
+		else if (/method\s*!==\s*['"]POST['"]/.test(segment)) methods = "POST";
+		out.set(path, methods);
+	}
+	return out;
+}
+
+/**
+ * 抽取 **bootstrap 响应**里实际声明的能力键（G2）。
+ * 只认 `/bootstrap` 处理器里的那个 `capabilities: {...}` 块——SSE hello 里也有
+ * `capabilities`，按"源码里第一个"抽取会误判（那样负向变异根本测不出来）。
+ */
+export function extractDeclaredCapabilities(source) {
+	const lines = source.split("\n");
+	const bootstrapAt = lines.findIndex((l) => /rest\s*===\s*['"]\/bootstrap['"]/.test(l));
+	const from = bootstrapAt >= 0 ? bootstrapAt : 0;
+	const tail = lines.slice(from).join("\n");
+	const m = /capabilities:\s*\{/.exec(tail);
+	if (!m) return new Set();
+	// 从 `{` 起做花括号配平，取出完整块
+	const open = tail.indexOf("{", m.index);
+	let depth = 0;
+	let end = -1;
+	for (let i = open; i < tail.length; i++) {
+		if (tail[i] === "{") depth++;
+		else if (tail[i] === "}") {
+			depth--;
+			if (depth === 0) {
+				end = i;
+				break;
+			}
+		}
+	}
+	if (end < 0) return new Set();
+	const block = tail.slice(open + 1, end);
+	return new Set([...block.matchAll(/([A-Za-z_][A-Za-z0-9_]*)\s*:/g)].map((x) => x[1]));
+}
+
+/** 未声明能力时的显式豁免理由（登记表要求二者必居其一）。 */
+export const NO_CAPABILITY_NEEDED = "端点级能力由 App 按 404/缺字段降级；能力声明机制覆盖的是帧/字段级特性";
+
+/**
+ * 双向比对。返回 `missing`（源码有、表里没有）、`stale`（表里有、源码没有）、
+ * `methodMismatch`（方法不符）与 `undeclaredCapabilities`（登记了未声明的能力键）。
+ */
+export function diffRegisteredEndpoints(source, registered = REGISTERED_ENDPOINTS) {
+	const dispatched = extractEndpointDetails(source);
+	const known = new Map(registered.map((e) => [e.path, e]));
+	const declared = extractDeclaredCapabilities(source);
+	const missing = [...dispatched.keys()].filter((p) => !known.has(p)).sort();
+	const stale = [...known.keys()].filter((p) => !dispatched.has(p)).sort();
+	const methodMismatch = [...dispatched.entries()]
+		.filter(([p, methods]) => known.has(p) && known.get(p).methods && known.get(p).methods !== methods)
+		.map(([p, methods]) => ({ path: p, registered: known.get(p).methods, source: methods }))
+		.sort((a, b) => a.path.localeCompare(b.path));
+	const undeclaredCapabilities = [...new Set(
+		registered.map((e) => e.capability).filter((c) => typeof c === "string" && c !== "" && !declared.has(c)),
+	)].sort();
+	const missingCapabilityField = registered.filter((e) => !("capability" in e)).map((e) => e.path).sort();
+	// 没关联能力键的必须给出**显式豁免理由**（G2：不允许"忘了写"和"确实不需要"长得一样）
+	const missingExemption = registered
+		.filter((e) => (e.capability === null || e.capability === undefined) && !(typeof e.why === "string" && e.why.trim() !== ""))
+		.map((e) => e.path)
+		.sort();
+	return { missing, stale, methodMismatch, undeclaredCapabilities, missingCapabilityField, missingExemption, dispatched, declared };
+}
+
+/** 已登记的 `/m/api/*` 端点（`path` 是去掉 `/m/api` 前缀后的部分）。 */
+export const REGISTERED_ENDPOINTS = Object.freeze([
+	{ path: "/account-usage", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/actions", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/attachment", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/balance", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/bootstrap", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/catalog", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/commands", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/defaults", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/dev/approval-test", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/diagnostics", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/directories", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/event-detail", methods: "GET", capability: "eventTimeline" },
+	{ path: "/events", methods: "GET", capability: "eventTimeline" },
+	{ path: "/feedback", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/files", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/files/upload", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/git/branches", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/git/capabilities", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/git/commit", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/git/graph", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/git/preview", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/git/repository", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/git/worktree", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/goal", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/history", methods: "GET", capability: "eventTimeline" },
+	{ path: "/jobs", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/jobs/kill", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/llm-providers", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/llm-providers/probe", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/messages", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/notifications", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/notifications/delete", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/notifications/read", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/plugin-update/check", methods: "GET", capability: null, auth: "required", why: NO_CAPABILITY_NEEDED },
+	{ path: "/plugin-update/prepare", methods: "POST", capability: null, auth: "required", why: NO_CAPABILITY_NEEDED },
+	{ path: "/plugin-update/log", methods: "GET", capability: null, auth: "required", why: NO_CAPABILITY_NEEDED },
+	{ path: "/plugin-update", methods: "POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/push-test", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/qr-config", methods: "GET", capability: null, auth: "local-privileged", why: NO_CAPABILITY_NEEDED },
+	{ path: "/queue", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/respond", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/send", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/send-receipt", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/session-config", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/sessions", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/sessions/archive", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/sessions/fork", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/sessions/stop", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/sessions/touch", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/sessions/unarchive", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/subagents", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/subagents/interrupt", methods: "GET/POST", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/todos", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/turn-outline", methods: "GET", capability: "turnOutline" },
+	{ path: "/update/apk", methods: "GET", capability: null, auth: "anonymous", why: NO_CAPABILITY_NEEDED },
+	{ path: "/update/manifest", methods: "GET", capability: null, auth: "required", why: NO_CAPABILITY_NEEDED },
+	{ path: "/update/plugin", methods: "GET", capability: null, auth: "required", why: NO_CAPABILITY_NEEDED },
+	{ path: "/usage", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+	{ path: "/workspaces", methods: "GET", capability: null, why: NO_CAPABILITY_NEEDED },
+]);

package/lib/git-read-bundled-provider.js

@@ -0,0 +1,255 @@
+import { constants as fsConstants } from "node:fs";
+import { realpath, open, lstat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+
+const UNTRACKED_PREVIEW_MAX = 512 * 1024;
+const SIGNATURE_SAMPLE_BYTES = 4096;
+const readOnlyNoFollow = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0);
+function sameRegularFile(expected, opened) {
+	return expected.isFile() && opened.isFile() && expected.dev === opened.dev && expected.ino === opened.ino;
+}
+async function readPrefix(path, maximum, expected) {
+	const handle = await open(path, readOnlyNoFollow);
+	try {
+		if (!sameRegularFile(expected, await handle.stat())) throw new Error("file changed while opening preview");
+		const buffer = Buffer.alloc(maximum + 1);
+		const { bytesRead } = await handle.read(buffer, 0, maximum + 1, 0);
+		return { bytes: buffer.subarray(0, bytesRead), truncated: bytesRead > maximum };
+	} finally { await handle.close(); }
+}
+async function sampledFileSignature(path, info) {
+	const handle = await open(path, readOnlyNoFollow);
+	try {
+		if (!sameRegularFile(info, await handle.stat())) throw new Error("file changed while sampling worktree");
+		const first = Buffer.alloc(Math.min(SIGNATURE_SAMPLE_BYTES, info.size));
+		const firstRead = await handle.read(first, 0, first.length, 0);
+		let last = Buffer.alloc(0);
+		if (info.size > SIGNATURE_SAMPLE_BYTES) {
+			last = Buffer.alloc(SIGNATURE_SAMPLE_BYTES);
+			const read = await handle.read(last, 0, last.length, Math.max(0, info.size - last.length));
+			last = last.subarray(0, read.bytesRead);
+		}
+		return createHash("sha256").update(`${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}:${info.ctimeMs}:`).update(first.subarray(0, firstRead.bytesRead)).update(last).digest("hex");
+	} finally { await handle.close(); }
+}
+
+function gitError(code, status, message = code) {
+	const error = new Error(message);
+	error.code = code;
+	error.status = status;
+	return error;
+}
+
+/** Bundled, read-only Git provider. Every command uses the host subprocess service. */
+export function createBundledGitReadProvider(ctx) {
+	const get = (name) => {
+		try { return ctx.get?.(name); } catch { return undefined; }
+	};
+	const subprocess = () => get("subprocess") ?? ctx.subprocess;
+	const workspaces = () => (get("workspaceRegistry")?.list?.() ?? [])
+		.map((entry) => entry?.path).filter((path) => typeof path === "string" && path !== "");
+	const inside = (child, parent) => {
+		const value = relative(resolve(parent), resolve(child));
+		return value === "" || (value !== ".." && !value.startsWith(`..${sep}`) && !isAbsolute(value));
+	};
+	const assertWorkspace = async (path) => {
+		if (typeof path !== "string" || path === "") throw gitError("workspace-not-allowed", 403);
+		let canonical;
+		try { canonical = await realpath(path); } catch { throw gitError("workspace-not-allowed", 403); }
+		const roots = await Promise.all(workspaces().map((root) => realpath(root).catch(() => null)));
+		if (!roots.some((root) => root && inside(canonical, root))) throw gitError("workspace-not-allowed", 403);
+		return canonical;
+	};
+	const run = async (root, args, disableFilters = false, allowNoMatches = false) => {
+		root = await assertWorkspace(root);
+		const executor = subprocess();
+		if (!executor?.spawn) throw gitError("git-provider-unavailable", 503);
+		const noHooksPath = process.platform === "win32" ? "NUL" : "/dev/null";
+		let filterOverrides = [];
+		if (disableFilters) {
+			const names = await run(root, ["config", "--null", "--name-only", "--get-regexp", "^filter\\..*\\.(clean|process)$"], false, true);
+			filterOverrides = names.split("\0").filter(Boolean).flatMap((name) => ["-c", `${name}=`]);
+		}
+		const child = executor.spawn({
+			argv: [
+				process.platform === "win32" ? "git.exe" : "git",
+				"-c", "core.fsmonitor=false",
+				"-c", `core.hooksPath=${noHooksPath}`,
+				...filterOverrides,
+				"-C", root,
+				"--no-optional-locks",
+				...args,
+			],
+			cwd: root,
+			// Prevent ambient Git repository/config overrides from redirecting a
+			// session-authorized read. Undefined values are seam tombstones.
+			env: {
+				GIT_TERMINAL_PROMPT: "0",
+				GCM_INTERACTIVE: "never",
+				GIT_DIR: undefined,
+				GIT_WORK_TREE: undefined,
+				GIT_INDEX_FILE: undefined,
+				GIT_COMMON_DIR: undefined,
+				GIT_OBJECT_DIRECTORY: undefined,
+				GIT_ALTERNATE_OBJECT_DIRECTORIES: undefined,
+				GIT_CONFIG: undefined,
+				GIT_CONFIG_PARAMETERS: undefined,
+				GIT_CONFIG_COUNT: "0",
+				// Trace destinations open files even for otherwise read-only Git commands.
+				...Object.fromEntries(Object.keys(process.env).filter((key) => /^GIT_TRACE(?:2)?(?:_|$)/.test(key)).map((key) => [key, undefined])),
+				GIT_TRACE: undefined,
+				GIT_TRACE2: undefined,
+				GIT_TRACE2_EVENT: undefined,
+				GIT_TRACE2_PERF: undefined,
+			},
+			stdio: { stdin: "ignore", stdout: { maxBytes: 8 * 1024 * 1024 }, stderr: { maxBytes: 1024 * 1024 } },
+			graceMs: 10_000,
+		});
+		const done = await child.done;
+		const stdoutResult = await child.collected?.stdout?.readFrom?.(0);
+		const stderrResult = await child.collected?.stderr?.readFrom?.(0);
+		if (stdoutResult?.lossy || stderrResult?.lossy) {
+			throw gitError("git-output-too-large", 413);
+		}
+		const stdout = stdoutResult?.text ?? "";
+		const stderr = stderrResult?.text ?? "";
+		if (done?.exitCode !== 0) {
+			if (allowNoMatches && done?.exitCode === 1) return "";
+			if (/not a git repository/i.test(stderr)) throw gitError("not-git-repository", 404);
+			throw gitError("git-command-failed", 400);
+		}
+		return stdout;
+	};
+	const repositoryRoot = async (cwd) => {
+		const allowed = await assertWorkspace(cwd);
+		const root = (await run(allowed, ["rev-parse", "--show-toplevel"])).trim();
+		return assertWorkspace(root);
+	};
+	return {
+		contractVersion: "1.0.0",
+		capabilities() {
+			const available = Boolean(subprocess()?.spawn) && workspaces().length > 0;
+			return { available, reason: available ? null : !subprocess()?.spawn ? "git-provider-unavailable" : "workspace-registry-unavailable" };
+		},
+		repositoryRoot,
+		async refSignature(root) {
+			let refs = "";
+			try { refs = await run(root, ["show-ref", "--head", "--dereference"]); } catch (error) { if (error?.code !== "git-command-failed") throw error; }
+			return createHash("sha256").update(refs).digest("hex");
+		},
+		async repositoryInfo(root) {
+			let currentBranch = null, headOid = null;
+			try { currentBranch = (await run(root, ["symbolic-ref", "--quiet", "HEAD"])).trim() || null; } catch (error) { if (error?.code !== "git-command-failed") throw error; }
+			try { headOid = (await run(root, ["rev-parse", "--verify", "HEAD"])).trim() || null; } catch (error) { if (error?.code !== "git-command-failed") throw error; }
+			return { ...(headOid ? { headOid } : {}), ...(currentBranch ? { currentBranch } : {}), detached: Boolean(headOid && !currentBranch), empty: !headOid };
+		},
+		async resolveTip(root, ref) {
+			return (await run(root, ["rev-parse", "--verify", `${ref}^{commit}`])).trim();
+		},
+		async graph(root, { refs, offset, limit }) {
+			if (refs.length === 0) return [];
+			const text = await run(root, ["log", "--topo-order", "--date-order", `--skip=${offset}`, `--max-count=${limit}`, "--decorate=full", "--format=%H%x1f%P%x1f%an%x1f%at%x1f%s%x1f%D%x00", ...refs]);
+			return text.split("\0").map((record) => record.replace(/^[\r\n]+|[\r\n]+$/g, "")).filter(Boolean).map((record) => {
+				const [oid, parents, author, timestamp, subject, decorations] = record.split("\x1f");
+				return { oid, parents: parents ? parents.split(" ") : [], author, timestamp: Number(timestamp) || 0, subject, refs: decorations ? decorations.split(",").map((value) => value.trim()).filter(Boolean) : [] };
+			});
+		},
+		async commit(root, oid) {
+			if (typeof oid !== "string" || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(oid)) throw gitError("invalid-oid", 400);
+			const metadata = (await run(root, ["show", "-s", "--format=%H%x1f%P%x1f%an%x1f%at%x1f%B%x00", oid])).split("\0")[0].split("\x1f");
+			const [hash, parentText, author, timestamp, ...messageParts] = metadata;
+			const diffBase = parentText ? [parentText.split(" ")[0], hash] : ["--root", hash];
+			const statusParts = (await run(root, ["diff-tree", "--no-commit-id", "-r", "-M", "--name-status", "-z", ...diffBase])).split("\0");
+			const files = [];
+			for (let index = 0; index < statusParts.length;) {
+				const code = statusParts[index++];
+				if (!code) continue;
+				const renamed = code.startsWith("R") || code.startsWith("C");
+				const oldPath = renamed ? statusParts[index++] : undefined;
+				const path = statusParts[index++];
+				if (!path) break;
+				const statuses = { A: "added", M: "modified", D: "deleted", R: "renamed", C: "copied", T: "type-changed" };
+				files.push({ path, ...(oldPath ? { oldPath } : {}), status: statuses[code[0]] ?? "modified" });
+			}
+			const statParts = (await run(root, ["diff-tree", "--no-commit-id", "-r", "-M", "--numstat", "-z", ...diffBase])).split("\0");
+			const stats = new Map();
+			for (let index = 0; index < statParts.length;) {
+				const record = statParts[index++];
+				if (!record) continue;
+				const firstTab = record.indexOf("\t");
+				const secondTab = record.indexOf("\t", firstTab + 1);
+				if (firstTab < 0 || secondTab < 0) continue;
+				const added = record.slice(0, firstTab);
+				const deleted = record.slice(firstTab + 1, secondTab);
+				let path = record.slice(secondTab + 1);
+				if (!path) { index++; path = statParts[index++] ?? ""; }
+				stats.set(path, { binary: added === "-" || deleted === "-", additions: added === "-" ? null : Number(added), deletions: deleted === "-" ? null : Number(deleted) });
+			}
+			for (const file of files) Object.assign(file, stats.get(file.path) ?? { binary: false, additions: 0, deletions: 0 });
+			return { oid: hash, parents: parentText ? parentText.split(" ") : [], author, timestamp: Number(timestamp) || 0, message: messageParts.join("\x1f").trim(), files };
+		},
+		async worktree(root) {
+			const text = await run(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], true);
+			const parts = text.split("\0"); const entries = [];
+			for (let i = 0; i < parts.length;) {
+				const record = parts[i++]; if (!record) continue;
+				const code = record.slice(0, 2); let path = record.slice(3); let oldPath;
+				if (/[RC]/.test(code)) { oldPath = parts[i++] ?? ""; }
+				const status = code.includes("U") || code === "AA" || code === "DD" ? "conflicted" : code === "??" ? "untracked" : "modified";
+				entries.push({ path, ...(oldPath ? { oldPath } : {}), status, conflicted: status === "conflicted", index: code[0] !== " " && code !== "??", worktree: code[1] !== " " && code !== "??" });
+			}
+			let signatureMaterial = text;
+			for (const entry of entries) {
+				if (entry.status !== "untracked" && !entry.worktree) continue;
+				try { const target = resolve(root, entry.path); const info = await lstat(target); signatureMaterial += `\\0${entry.path}:${info.isSymbolicLink() ? "symlink" : info.isFile() ? await sampledFileSignature(target, info) : "special"}`; } catch { signatureMaterial += `\\0${entry.path}:missing`; }
+			}
+			try { signatureMaterial += await run(root, ["--literal-pathspecs", "diff", "--raw", "-z", "--no-abbrev", "HEAD"], true); } catch (error) { if (error?.code !== "git-command-failed") throw error; }
+			try { signatureMaterial += await run(root, ["--literal-pathspecs", "diff", "--raw", "-z", "--no-abbrev", "--cached"], true); } catch (error) { if (error?.code !== "git-command-failed") throw error; }
+			const signature = createHash("sha256").update(signatureMaterial).digest("hex");
+			return { entries, signature };
+		},
+		async worktreePreview(root, kind, path) {
+			const args = ["--literal-pathspecs", "diff", "--unified=999999", "--no-ext-diff", "--no-textconv", "--no-color", "--binary"];
+			if (kind === "staged") args.push("--cached");
+			args.push("--", path);
+			if (kind === "untracked") {
+				try {
+					const target = resolve(root, path); const info = await lstat(target);
+					if (info.isSymbolicLink()) return { diff: "", binary: false, additions: null, deletions: null, notice: "symlink preview omitted" };
+					if (!info.isFile()) return { diff: "", binary: false, additions: null, deletions: null, notice: "special file preview omitted" };
+					const { bytes, truncated } = await readPrefix(target, UNTRACKED_PREVIEW_MAX, info);
+					const binary = bytes.includes(0);
+					return { diff: binary ? "" : bytes.toString("utf8"), binary, truncated, additions: null, deletions: null, ...(binary ? { notice: "binary preview omitted" } : {}) };
+				} catch { return { diff: "", binary: false, additions: 0, deletions: 0, notice: "unavailable" }; }
+			}
+			return { diff: await run(root, args, true), binary: false, additions: null, deletions: null };
+		},
+		async commitPreview(root, oid, path) {
+			const commit = await this.commit(root, oid);
+			if (!commit.parents.length) return { diff: await run(root, ["--literal-pathspecs", "diff-tree", "--root", "--no-commit-id", "-p", "-r", "--unified=999999", "--no-ext-diff", "--no-textconv", "--no-color", "--binary", oid, "--", path]), binary: false };
+			return { diff: await run(root, ["--literal-pathspecs", "diff", "--unified=999999", "--no-ext-diff", "--no-textconv", "--no-color", "--binary", `${oid}^1`, oid, "--", path]), binary: false };
+		},
+		async branches(root) {
+			const text = await run(root, ["for-each-ref", "--format=%(HEAD)%09%(refname)%09%(objectname)%09%(upstream:short)%00", "refs/heads", "refs/remotes"]);
+			const rows = text.split("\0").map((record) => record.replace(/^[\r\n]+|[\r\n]+$/g, "")).filter(Boolean);
+			const branches = [];
+			for (const row of rows) {
+				const [head, ref, oid, upstream = ""] = row.split("\t");
+				if (ref.endsWith("/HEAD")) continue;
+				const local = ref.startsWith("refs/heads/");
+				let ahead = 0, behind = 0;
+				if (local && upstream) {
+					const counts = (await run(root, ["rev-list", "--left-right", "--count", `${ref}...${upstream}`])).trim().split(/\s+/).map(Number);
+					[ahead, behind] = counts;
+				}
+				branches.push({
+					name: ref, displayName: ref.replace(/^refs\/(?:heads|remotes)\//, ""), oid,
+					kind: local ? "local" : "remote", current: local && head === "*",
+					tracking: local && upstream ? `refs/remotes/${upstream}` : null, ahead, behind,
+				});
+			}
+			return branches;
+		},
+	};
+}