nano-git 0.1.0

package/dist/transport/protocol/pkt-line.mjs

@@ -0,0 +1,195 @@
+import { GitError } from "../../core/errors.mjs";
+//#region src/transport/protocol/pkt-line.ts
+/**
+* pkt-line 帧编解码
+*
+* Git 协议的基本传输单元。每条帧以 4 字符十六进制长度前缀开头，
+* 后跟对应长度的负载数据。
+*
+* 帧类型：
+* - 数据帧：长度前缀在 0004–FFF4 之间（含 4 字节前缀自身）
+* - 0000：flush-pkt，表示结束
+* - 0001：delimiter-pkt（协议 v2）
+* - 0002：response-end-pkt（协议 v2）
+*
+* @example
+* ```ts
+* const data = encodePktLine("hello");
+* console.log(data.toString("hex")); // => "000968656c6c6f"
+* ```
+*
+* @see https://github.com/git/git/blob/master/Documentation/technical/pkt-line.txt
+*/
+/**
+* pkt-line 协议错误
+*
+* 当 pkt-line 数据格式不符合 Git 协议规范时抛出。
+*/
+var PktLineError = class extends GitError {
+	constructor(message) {
+		super(`pkt-line error: ${message}`);
+		this.name = "PktLineError";
+	}
+};
+/** pkt-line 特殊帧的十六进制编码 */
+const FLUSH_PKT_HEX = "0000";
+const DELIMITER_PKT_HEX = "0001";
+const RESPONSE_END_PKT_HEX = "0002";
+/** pkt-line 长度前缀的字节数 */
+const LENGTH_PREFIX_BYTES = 4;
+/** pkt-line 数据帧的最大总长度（含 4 字节前缀） */
+const MAX_PACKET_SIZE = 65524;
+/** pkt-line 数据帧的最大负载长度 */
+const MAX_PAYLOAD_SIZE = MAX_PACKET_SIZE - LENGTH_PREFIX_BYTES;
+/**
+* 编码 pkt-line 数据帧
+*
+* 将 payload 编码为 pkt-line 格式："XXXX<payload>"
+* 其中 XXXX 是含 4 字节前缀的总长度（十六进制）。
+*
+* @param payload - 负载数据（字符串或 Buffer）
+* @returns pkt-line 编码后的 Buffer
+*
+* @example
+* ```ts
+* const buf = encodePktLine("hello");
+* console.log(buf.toString("utf-8")); // => "0009hello"
+* ```
+*/
+function encodePktLine(payload) {
+	const data = typeof payload === "string" ? Buffer.from(payload, "utf-8") : payload;
+	if (data.length > MAX_PAYLOAD_SIZE) throw new PktLineError(`Payload too large: ${data.length} bytes (max ${MAX_PAYLOAD_SIZE})`);
+	const prefix = (data.length + LENGTH_PREFIX_BYTES).toString(16).padStart(4, "0").toUpperCase();
+	return Buffer.concat([Buffer.from(prefix, "utf-8"), data]);
+}
+/**
+* 生成 flush-pkt
+*
+* @returns Buffer("0000")
+*
+* @example
+* ```ts
+* const buf = encodeFlushPkt();
+* console.log(buf.toString("utf-8")); // => "0000"
+* ```
+*/
+function encodeFlushPkt() {
+	return Buffer.from(FLUSH_PKT_HEX, "utf-8");
+}
+/**
+* 生成 delimiter-pkt（协议 v2）
+*
+* @returns Buffer("0001")
+*/
+function encodeDelimiterPkt() {
+	return Buffer.from(DELIMITER_PKT_HEX, "utf-8");
+}
+/**
+* 生成 response-end-pkt（协议 v2）
+*
+* @returns Buffer("0002")
+*/
+function encodeResponseEndPkt() {
+	return Buffer.from(RESPONSE_END_PKT_HEX, "utf-8");
+}
+/**
+* 解析 pkt-line 编码的完整数据流
+*
+* 将包含一个或多个 pkt-line 帧的 Buffer 解析为 PktLine 数组。
+*
+* @param data - 完整的 pkt-line 编码数据
+* @returns 解析后的 PktLine 列表
+*
+* @example
+* ```ts
+* const lines = parsePktLines(Buffer.from("0009hello0000", "utf-8"));
+* // lines[0] = { type: "data", payload: Buffer("hello") }
+* // lines[1] = { type: "flush" }
+* ```
+*/
+function parsePktLines(data) {
+	const result = [];
+	let offset = 0;
+	while (offset < data.length) {
+		if (offset + LENGTH_PREFIX_BYTES > data.length) throw new PktLineError(`Truncated pkt-line: need ${LENGTH_PREFIX_BYTES} bytes for length prefix, got ${data.length - offset}`);
+		const hex = data.subarray(offset, offset + LENGTH_PREFIX_BYTES).toString("utf-8");
+		if (!/^[0-9a-fA-F]{4}$/.test(hex)) throw new PktLineError(`Invalid pkt-line length: "${hex}"`);
+		const length = parseInt(hex, 16);
+		offset += LENGTH_PREFIX_BYTES;
+		if (length === 0) result.push({ type: "flush" });
+		else if (length === 1) result.push({ type: "delimiter" });
+		else if (length === 2) result.push({ type: "response-end" });
+		else {
+			if (length < LENGTH_PREFIX_BYTES) throw new PktLineError(`Invalid pkt-line length: ${length} (minimum data length is ${LENGTH_PREFIX_BYTES})`);
+			if (length > MAX_PACKET_SIZE) throw new PktLineError(`Invalid pkt-line length: ${length} (max ${MAX_PACKET_SIZE})`);
+			const payloadLength = length - LENGTH_PREFIX_BYTES;
+			if (offset + payloadLength > data.length) throw new PktLineError(`Truncated pkt-line: expected ${payloadLength} bytes of payload, got ${data.length - offset}`);
+			const payload = data.subarray(offset, offset + payloadLength);
+			offset += payloadLength;
+			result.push({
+				type: "data",
+				payload
+			});
+		}
+	}
+	return result;
+}
+/**
+* 解析 pkt-line 编码的数据流，将有效帧与尾部原始二进制数据分离
+*
+* 与 {@link parsePktLines} 不同，此函数不会因尾部存在非 pkt-line 原始数据而抛出错误，
+* 而是将剩余数据作为 trailing 返回。适用于解析非 side-band 编码的 upload-pack 响应：
+* pkt-line 头部（ACK/NAK）+ 尾部原始 packfile 数据。
+*
+* @param data - 可能包含尾部原始数据的 pkt-line 编码 buffer
+* @returns 解析出的帧列表和尾部原始数据
+*
+* @example
+* ```ts
+* const { lines, trailing } = splitPktLinesFromBuffer(
+*   Buffer.concat([encodePktLine("NAK\n"), rawPackfile]),
+* );
+* // lines[0] = { type: "data", payload: Buffer("NAK\n") }
+* // trailing = <raw packfile>
+* ```
+*/
+function splitPktLinesFromBuffer(data) {
+	const lines = [];
+	let offset = 0;
+	while (offset < data.length) {
+		if (offset + LENGTH_PREFIX_BYTES > data.length) break;
+		const hex = data.subarray(offset, offset + LENGTH_PREFIX_BYTES).toString("utf-8");
+		if (!/^[0-9a-fA-F]{4}$/.test(hex)) break;
+		const length = parseInt(hex, 16);
+		if (length === 0) {
+			lines.push({ type: "flush" });
+			offset += LENGTH_PREFIX_BYTES;
+			continue;
+		}
+		if (length === 1) {
+			lines.push({ type: "delimiter" });
+			offset += LENGTH_PREFIX_BYTES;
+			continue;
+		}
+		if (length === 2) {
+			lines.push({ type: "response-end" });
+			offset += LENGTH_PREFIX_BYTES;
+			continue;
+		}
+		if (length < LENGTH_PREFIX_BYTES || length > MAX_PACKET_SIZE) break;
+		const payloadLength = length - LENGTH_PREFIX_BYTES;
+		if (offset + LENGTH_PREFIX_BYTES + payloadLength > data.length) break;
+		const payload = data.subarray(offset + LENGTH_PREFIX_BYTES, offset + LENGTH_PREFIX_BYTES + payloadLength);
+		lines.push({
+			type: "data",
+			payload
+		});
+		offset += LENGTH_PREFIX_BYTES + payloadLength;
+	}
+	return {
+		lines,
+		trailing: Buffer.from(data.subarray(offset))
+	};
+}
+//#endregion
+export { PktLineError, encodeDelimiterPkt, encodeFlushPkt, encodePktLine, encodeResponseEndPkt, parsePktLines, splitPktLinesFromBuffer };

package/dist/transport/protocol/ref-advertisement.mjs

@@ -0,0 +1,185 @@
+import { sha1 } from "../../core/types.mjs";
+import { PktLineError, parsePktLines } from "./pkt-line.mjs";
+//#region src/transport/protocol/ref-advertisement.ts
+/**
+* 引用广告解析
+*
+* 将服务端通过 pkt-line 编码的 ref advertisement 数据解析为
+* 结构化的 RefAdvertisement 对象。
+*
+* 数据流格式：
+*   # service=git-upload-pack\n
+*   0000                                  (flush)
+*   <hash> <refname>\0<capabilities>\n    (第一行，capabilities 紧跟在 NUL 后)
+*   <hash> <refname>\n                    (后续引用行)
+*   <hash> <refname>^{}\n                 (peeled tag)
+*   0000                                  (flush 结束)
+*
+* @see https://git-scm.com/docs/pack-protocol#_reference_discovery
+*/
+/**
+* Ref 广告解析错误
+*
+* 当 ref advertisement 数据格式不符合 Git 协议规范时抛出。
+*/
+var RefAdvertisementError = class extends PktLineError {
+	constructor(message) {
+		super(`ref-advertisement: ${message}`);
+		this.name = "RefAdvertisementError";
+	}
+};
+/** 服务端头信息前缀 */
+const SERVICE_HEADER_PREFIX = "# service=";
+/** Peeled tag 后缀 */
+const PEELED_TAG_SUFFIX = "^{}";
+/**
+* 解析 ref advertisement 数据
+*
+* @param data - 来自服务端的完整 ref advertisement 响应体（pkt-line 编码）
+* @param service - 服务名称（如 "git-upload-pack"）
+* @returns 结构化的 RefAdvertisement
+*
+* @example
+* ```ts
+* const data = await fetch("https://example.com/repo/info/refs?service=git-upload-pack")
+*   .then(r => r.body);
+* const adv = parseRefAdvertisement(data, "git-upload-pack");
+* console.log(adv.refs[0].name); // "refs/heads/main"
+* ```
+*/
+function parseRefAdvertisement(data, service) {
+	const pktLines = parsePktLines(data);
+	if (pktLines.length === 0) throw new RefAdvertisementError("Empty ref advertisement");
+	let idx = 0;
+	if (idx < pktLines.length) {
+		const firstPkt = pktLines[idx];
+		if (firstPkt.type === "data") {
+			const firstPayload = firstPkt.payload.toString("utf-8");
+			if (firstPayload.startsWith(SERVICE_HEADER_PREFIX)) {
+				const headerService = firstPayload.slice(10).trim();
+				if (headerService !== service) throw new RefAdvertisementError(`Expected service "${service}" but got "${headerService}"`);
+				idx++;
+				if (idx >= pktLines.length || pktLines[idx].type !== "flush") throw new RefAdvertisementError(`Expected flush-pkt after service header "# service=${service}"`);
+				idx++;
+			}
+		}
+	}
+	const refs = [];
+	let capabilities = {};
+	for (; idx < pktLines.length; idx++) {
+		const line = pktLines[idx];
+		if (line.type !== "data") break;
+		const payload = line.payload;
+		const nullIndex = payload.indexOf(0);
+		const refLine = (nullIndex === -1 ? payload.toString("utf-8") : payload.subarray(0, nullIndex).toString("utf-8")).trim();
+		if (refLine.length === 0) continue;
+		if (nullIndex !== -1 && payload.length > nullIndex + 1) capabilities = parseCapabilities(payload.subarray(nullIndex + 1).toString("utf-8"));
+		if (refLine.endsWith(PEELED_TAG_SUFFIX)) {
+			const peeledHash = parseHashFromRefLine(refLine);
+			const tagName = refLine.slice(0, -3).split(" ").slice(1).join(" ").trim();
+			if (tagName === "capabilities") continue;
+			if (refs.length === 0) throw new RefAdvertisementError(`Orphaned peeled tag line "${refLine}": no preceding ref`);
+			const lastRef = refs[refs.length - 1];
+			if (lastRef.name !== tagName) throw new RefAdvertisementError(`Peeled tag name "${tagName}" does not match previous ref "${lastRef.name}"`);
+			if (!lastRef.name.startsWith("refs/tags/")) throw new RefAdvertisementError(`Peeled tag line "${refLine}" follows non-tag ref "${lastRef.name}"`);
+			lastRef.peeled = peeledHash;
+			continue;
+		}
+		const ref = parseRefLine(refLine);
+		refs.push(ref);
+	}
+	applySymrefToRefs(capabilities, refs);
+	const defaultBranch = computeDefaultBranch(capabilities, refs);
+	return {
+		capabilities,
+		refs,
+		defaultBranch
+	};
+}
+/**
+* 从 ref 行中提取 hash
+*
+* @param line - 类似 "95d09f2b... refs/tags/v1.0^{}" 的行
+* @returns SHA1 哈希
+*/
+function parseHashFromRefLine(line) {
+	const hashStr = line.split(" ")[0];
+	if (!hashStr) throw new RefAdvertisementError(`Cannot parse hash from ref line: "${line}"`);
+	return sha1(hashStr);
+}
+/**
+* 解析单条 ref 行
+*
+* @param line - 类似 "95d09f2b... refs/heads/main" 的行
+* @returns RemoteRef 对象
+*/
+function parseRefLine(line) {
+	const spaceIndex = line.indexOf(" ");
+	if (spaceIndex === -1) throw new RefAdvertisementError(`Invalid ref line: "${line}"`);
+	const hashStr = line.substring(0, spaceIndex);
+	const name = line.substring(spaceIndex + 1).trim();
+	if (hashStr.length !== 40) throw new RefAdvertisementError(`Invalid hash in ref line: "${line}"`);
+	return {
+		hash: sha1(hashStr),
+		name
+	};
+}
+/**
+* 解析 capabilities 字符串
+*
+* capabilities 以空格分隔，可能带参数（key=value）或不带参数（key）
+*
+* @param capsStr - 如 "multi_ack thin-pack side-band side-band-64k ofs-delta shallow deepen-since deepen-not deepen-relative no-progress include-tag multi_ack_detailed symref=HEAD:refs/heads/main agent=git/2.45.1"
+* @returns 解析后的 capabilities 对象
+*/
+function parseCapabilities(capsStr) {
+	const caps = {};
+	const tokens = capsStr.split(" ");
+	for (const token of tokens) {
+		if (token.length === 0) continue;
+		const eqIndex = token.indexOf("=");
+		if (eqIndex === -1) caps[token] = true;
+		else {
+			const key = token.substring(0, eqIndex);
+			caps[key] = token.substring(eqIndex + 1);
+		}
+	}
+	return caps;
+}
+/**
+* 从 capabilities 中提取 symref=HEAD:<target>，填充到 refs 中 HEAD ref 的 symrefTarget
+*
+* Git 服务端通过 `symref=HEAD:refs/heads/main` 能力声明默认分支。
+* 解析后将目标写入对应 HEAD ref 的 `symrefTarget` 字段，供 fetch 层据此设置本地 HEAD。
+*
+* @param capabilities - 解析后的 capabilities 对象
+* @param refs - refs 数组（原地修改 HEAD ref 的 symrefTarget）
+*/
+function applySymrefToRefs(capabilities, refs) {
+	const symref = capabilities["symref"];
+	if (typeof symref !== "string") return;
+	const colonIndex = symref.indexOf(":");
+	if (colonIndex === -1) return;
+	const headName = symref.substring(0, colonIndex);
+	const target = symref.substring(colonIndex + 1);
+	for (const ref of refs) if (ref.name === headName) {
+		ref.symrefTarget = target;
+		return;
+	}
+}
+/**
+* 从广告数据推断默认分支（唯一解析规则）
+*/
+function computeDefaultBranch(capabilities, refs) {
+	const symref = capabilities["symref"];
+	if (typeof symref === "string") {
+		const colonIndex = symref.indexOf(":");
+		if (colonIndex !== -1) {
+			if (symref.substring(0, colonIndex) === "HEAD") return symref.substring(colonIndex + 1);
+		}
+	}
+	const heads = refs.filter((r) => r.name.startsWith("refs/heads/"));
+	if (heads.length === 1) return heads[0].name;
+}
+//#endregion
+export { RefAdvertisementError, parseRefAdvertisement };

package/dist/transport/protocol/ref-collection.d.mts

@@ -0,0 +1,38 @@
+import { SHA1 } from "../../core/types.mjs";
+import { RefStore } from "../../core/types/refs.mjs";
+
+//#region src/transport/protocol/ref-collection.d.ts
+/**
+ * 获取本地 refs 的哈希映射
+ *
+ * 扫描 refs/ 下所有命名空间的引用，确保任意自定义目标命名空间
+ *（如 refs/mirrors/、refs/remotes/ 等）都能被正确检测到。
+ *
+ * @param refs - 本地引用存储
+ * @returns ref 名称 → SHA1 哈希的映射
+ *
+ * @example
+ * ```ts
+ * const refs = getLocalRefs(refStore);
+ * console.log(refs.get("refs/heads/main")); // SHA1 hash
+ * ```
+ */
+declare function getLocalRefs(refs: RefStore): Map<string, SHA1>;
+/**
+ * 将远程 ref 广告转换为哈希映射
+ *
+ * @param refs - 远程引用列表（如来自 advertisement）
+ * @returns ref 名称 → SHA1 哈希的映射
+ *
+ * @example
+ * ```ts
+ * const remoteMap = remoteRefsToMap(advertisement.refs);
+ * console.log(remoteMap.get("refs/heads/main"));
+ * ```
+ */
+declare function remoteRefsToMap(refs: Array<{
+  name: string;
+  hash: SHA1;
+}>): Map<string, SHA1>;
+//#endregion
+export { getLocalRefs, remoteRefsToMap };

package/dist/transport/protocol/ref-collection.mjs

@@ -0,0 +1,63 @@
+import { HEAD_REF } from "../../core/types/refs.mjs";
+import { resolveRefHash } from "../../refs/resolve.mjs";
+//#region src/transport/protocol/ref-collection.ts
+/**
+* 本地/远程引用收集
+*
+* 提供从 RefStore 收集本地 ref hash map 以及将远程 advertisement 转 map 的中立基础设施。
+* 不带 fetch/push 语义。
+*
+* @example
+* ```ts
+* import { getLocalRefs, remoteRefsToMap } from "./ref-collection.ts";
+*
+* const localRefs = getLocalRefs(refStore);
+* const remoteMap = remoteRefsToMap(advertisement.refs);
+* ```
+*/
+/**
+* 获取本地 refs 的哈希映射
+*
+* 扫描 refs/ 下所有命名空间的引用，确保任意自定义目标命名空间
+*（如 refs/mirrors/、refs/remotes/ 等）都能被正确检测到。
+*
+* @param refs - 本地引用存储
+* @returns ref 名称 → SHA1 哈希的映射
+*
+* @example
+* ```ts
+* const refs = getLocalRefs(refStore);
+* console.log(refs.get("refs/heads/main")); // SHA1 hash
+* ```
+*/
+function getLocalRefs(refs) {
+	const map = /* @__PURE__ */ new Map();
+	for (const refName of refs.listAll()) try {
+		const hash = resolveRefHash(refs, refName);
+		if (hash) map.set(refName, hash);
+	} catch {}
+	try {
+		const hash = resolveRefHash(refs, HEAD_REF);
+		if (hash) map.set(HEAD_REF, hash);
+	} catch {}
+	return map;
+}
+/**
+* 将远程 ref 广告转换为哈希映射
+*
+* @param refs - 远程引用列表（如来自 advertisement）
+* @returns ref 名称 → SHA1 哈希的映射
+*
+* @example
+* ```ts
+* const remoteMap = remoteRefsToMap(advertisement.refs);
+* console.log(remoteMap.get("refs/heads/main"));
+* ```
+*/
+function remoteRefsToMap(refs) {
+	const map = /* @__PURE__ */ new Map();
+	for (const ref of refs) map.set(ref.name, ref.hash);
+	return map;
+}
+//#endregion
+export { getLocalRefs, remoteRefsToMap };

package/dist/transport/protocol/ref-match.d.mts

@@ -0,0 +1,39 @@
+import { RemoteRef } from "./types.mjs";
+import { ParsedRefSpec } from "./refspec.mjs";
+
+//#region src/transport/protocol/ref-match.d.ts
+/**
+ * 判断远程引用是否匹配 refspec 源模式
+ *
+ * 通配符 refspec 使用 startsWith 匹配前缀，
+ * 精确 refspec 需要完全相等。
+ *
+ * @param ref - 远程引用
+ * @param spec - 解析后的 refspec
+ * @returns 是否匹配
+ *
+ * @example
+ * ```ts
+ * matchesRefSpec(
+ *   { name: "refs/heads/main", hash: sha1("...") },
+ *   parseRefSpec("refs/heads/*:refs/remotes/origin/*"),
+ * ); // => true
+ * ```
+ */
+declare function matchesRefSpec(ref: RemoteRef, spec: ParsedRefSpec): boolean;
+/**
+ * 将远程引用名转换为本地引用名
+ *
+ * @param refName - 远程引用名称
+ * @param spec - 解析后的 refspec
+ * @returns 映射后的本地引用名称
+ *
+ * @example
+ * ```ts
+ * mapRefName("refs/heads/main", parseRefSpec("refs/heads/*:refs/remotes/origin/*"))
+ * // => "refs/remotes/origin/main"
+ * ```
+ */
+declare function mapRefName(refName: string, spec: ParsedRefSpec): string;
+//#endregion
+export { mapRefName, matchesRefSpec };

package/dist/transport/protocol/ref-match.mjs

@@ -0,0 +1,42 @@
+//#region src/transport/protocol/ref-match.ts
+/**
+* 判断远程引用是否匹配 refspec 源模式
+*
+* 通配符 refspec 使用 startsWith 匹配前缀，
+* 精确 refspec 需要完全相等。
+*
+* @param ref - 远程引用
+* @param spec - 解析后的 refspec
+* @returns 是否匹配
+*
+* @example
+* ```ts
+* matchesRefSpec(
+*   { name: "refs/heads/main", hash: sha1("...") },
+*   parseRefSpec("refs/heads/*:refs/remotes/origin/*"),
+* ); // => true
+* ```
+*/
+function matchesRefSpec(ref, spec) {
+	if (spec.isWildcard) return ref.name.startsWith(spec.srcPattern);
+	return ref.name === spec.srcPattern;
+}
+/**
+* 将远程引用名转换为本地引用名
+*
+* @param refName - 远程引用名称
+* @param spec - 解析后的 refspec
+* @returns 映射后的本地引用名称
+*
+* @example
+* ```ts
+* mapRefName("refs/heads/main", parseRefSpec("refs/heads/*:refs/remotes/origin/*"))
+* // => "refs/remotes/origin/main"
+* ```
+*/
+function mapRefName(refName, spec) {
+	const suffix = refName.slice(spec.srcPattern.length);
+	return `${spec.dstPattern}${suffix}`;
+}
+//#endregion
+export { mapRefName, matchesRefSpec };

package/dist/transport/protocol/refspec.d.mts

@@ -0,0 +1,44 @@
+import { GitError } from "../../core/errors.mjs";
+import { RefMappingRule } from "./types.mjs";
+
+//#region src/transport/protocol/refspec.d.ts
+/**
+ * RefSpec 解析错误
+ */
+declare class RefSpecError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 解析后的 refspec
+ */
+interface ParsedRefSpec {
+  force: boolean;
+  srcPattern: string;
+  dstPattern: string;
+  /** 原始 refspec 是否包含通配符 * */
+  isWildcard: boolean;
+}
+/**
+ * 解析 refspec 字符串
+ *
+ * 格式: [+]<src>:<dst>
+ * 其中 + 表示 force push/fetch
+ * * 是通配符
+ *
+ * @example
+ * ```ts
+ * parseRefSpec("+refs/heads/*:refs/remotes/origin/*")
+ * // => { force: true, srcPattern: "refs/heads/", dstPattern: "refs/remotes/origin/", isWildcard: true }
+ * ```
+ */
+declare function parseRefSpec(refSpec: string): ParsedRefSpec;
+/**
+ * 将 RefMappingRule 转换为 ParsedRefSpec
+ */
+declare function mappingRuleToParsedSpec(rule: RefMappingRule): ParsedRefSpec;
+/**
+ * 将 ParsedRefSpec 转换为 RefMappingRule
+ */
+declare function parsedSpecToMappingRule(spec: ParsedRefSpec): RefMappingRule;
+//#endregion
+export { ParsedRefSpec, RefSpecError, mappingRuleToParsedSpec, parseRefSpec, parsedSpecToMappingRule };

package/dist/transport/protocol/refspec.mjs

@@ -0,0 +1,79 @@
+import { GitError } from "../../core/errors.mjs";
+//#region src/transport/protocol/refspec.ts
+/**
+* RefSpec 解析与转换
+*
+* 只处理 refspec/mapping rule 的语法与转换，不带 fetch/push 语义。
+*
+* @example
+* ```ts
+* import { parseRefSpec, mappingRuleToParsedSpec } from "./refspec.ts";
+*
+* const spec = parseRefSpec("+refs/heads/*:refs/remotes/origin/*");
+* console.log(spec.force, spec.srcPattern, spec.dstPattern);
+* ```
+*/
+/**
+* RefSpec 解析错误
+*/
+var RefSpecError = class extends GitError {
+	constructor(message) {
+		super(`Refspec error: ${message}`);
+		this.name = "RefSpecError";
+	}
+};
+/**
+* 解析 refspec 字符串
+*
+* 格式: [+]<src>:<dst>
+* 其中 + 表示 force push/fetch
+* * 是通配符
+*
+* @example
+* ```ts
+* parseRefSpec("+refs/heads/*:refs/remotes/origin/*")
+* // => { force: true, srcPattern: "refs/heads/", dstPattern: "refs/remotes/origin/", isWildcard: true }
+* ```
+*/
+function parseRefSpec(refSpec) {
+	const force = refSpec.startsWith("+");
+	const spec = force ? refSpec.slice(1) : refSpec;
+	const colonIndex = spec.indexOf(":");
+	if (colonIndex === -1) throw new RefSpecError(`Invalid refspec: "${refSpec}" (missing ":")`);
+	const src = spec.substring(0, colonIndex);
+	const dst = spec.substring(colonIndex + 1);
+	for (const [sideName, side] of [["src", src], ["dst", dst]]) {
+		const starCount = (side.match(/\*/g) ?? []).length;
+		if (starCount > 1) throw new RefSpecError(`Invalid refspec: "${refSpec}" (multiple wildcards in ${sideName})`);
+		if (starCount === 1 && !side.endsWith("*")) throw new RefSpecError(`Invalid refspec: "${refSpec}" (wildcard must be at the end of ${sideName})`);
+	}
+	const srcHasStar = src.endsWith("*");
+	if (srcHasStar !== dst.endsWith("*")) throw new RefSpecError(`Invalid refspec: "${refSpec}" (wildcard must appear on both sides)`);
+	const isWildcard = srcHasStar;
+	return {
+		force,
+		srcPattern: src.replace(/\*$/, ""),
+		dstPattern: dst.replace(/\*$/, ""),
+		isWildcard
+	};
+}
+/**
+* 将 RefMappingRule 转换为 ParsedRefSpec
+*/
+function mappingRuleToParsedSpec(rule) {
+	const forceFromSource = rule.source.startsWith("+");
+	const cleanSource = forceFromSource ? rule.source.slice(1) : rule.source;
+	return parseRefSpec(`${rule.force ?? forceFromSource ? "+" : ""}${cleanSource}:${rule.target}`);
+}
+/**
+* 将 ParsedRefSpec 转换为 RefMappingRule
+*/
+function parsedSpecToMappingRule(spec) {
+	return {
+		source: spec.isWildcard ? `${spec.srcPattern}*` : spec.srcPattern,
+		target: spec.isWildcard ? `${spec.dstPattern}*` : spec.dstPattern,
+		force: spec.force
+	};
+}
+//#endregion
+export { RefSpecError, mappingRuleToParsedSpec, parseRefSpec, parsedSpecToMappingRule };