nano-git 0.1.0

package/dist/transport/client/receive-pack/http.mjs

@@ -0,0 +1,99 @@
+import { GitError } from "../../../core/errors.mjs";
+import { RefAdvertisementError, parseRefAdvertisement } from "../../protocol/ref-advertisement.mjs";
+//#region src/transport/client/receive-pack/http.ts
+/**
+* Smart HTTP 传输层 — Receive-Pack 客户端
+*
+* 基于 Bun 内置 fetch() 的 Git Smart HTTP 协议 HTTP 适配器。
+* 仅提供 receive-pack（push）客户端，upload-pack（fetch）请使用 v2 协议。
+*
+* @see https://git-scm.com/docs/http-protocol
+*/
+/**
+* Smart HTTP 传输错误
+*
+* 当 HTTP 层面的传输出错时抛出（网络错误、非预期状态码等）。
+*/
+var SmartHttpError = class extends GitError {
+	statusCode;
+	constructor(message, statusCode) {
+		super(`Smart HTTP error: ${message}${statusCode !== void 0 ? ` (status ${statusCode})` : ""}`);
+		this.statusCode = statusCode;
+		this.name = "SmartHttpError";
+	}
+};
+function applyAuthHeaders(base, auth) {
+	const result = { ...auth?.headers };
+	if (auth?.token) result["Authorization"] = `Bearer ${auth.token}`;
+	return {
+		...base,
+		...result
+	};
+}
+async function readResponseBody(response, context) {
+	try {
+		return Buffer.from(await response.arrayBuffer());
+	} catch (err) {
+		throw new SmartHttpError(`Failed to read response body (${context}): ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+function assertContentType(actual, expected, context) {
+	if (!actual.includes(expected)) throw new SmartHttpError(`Unexpected content type: ${actual} (expected ${expected}) (${context})`);
+}
+/** receive-pack HTTP 端点配置 */
+const RECEIVE_PACK_ADVERTISE_SERVICE = "git-receive-pack";
+const RECEIVE_PACK_ADVERTISE_CONTENT_TYPE = "application/x-git-receive-pack-advertisement";
+const RECEIVE_PACK_RPC_PATH = "/git-receive-pack";
+const RECEIVE_PACK_RPC_CONTENT_TYPE = "application/x-git-receive-pack-request";
+const RECEIVE_PACK_RESULT_CONTENT_TYPE = "application/x-git-receive-pack-result";
+/**
+* 创建 receive-pack HTTP 客户端
+*
+* @example
+* ```ts
+* const client = createReceivePackHttpClient("https://github.com/user/repo");
+* const adv = await client.advertise();
+* const raw = await client.request(body);
+* ```
+*/
+function createReceivePackHttpClient(baseUrl, auth) {
+	const normalizedUrl = baseUrl.replace(/\/+$/, "");
+	return {
+		async advertise() {
+			const url = `${normalizedUrl}/info/refs?service=${RECEIVE_PACK_ADVERTISE_SERVICE}`;
+			let response;
+			try {
+				response = await fetch(url, { headers: applyAuthHeaders({}, auth) });
+			} catch (err) {
+				throw new SmartHttpError(`Failed to fetch ref advertisement from ${url}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			if (!response.ok) throw new SmartHttpError(`Failed to fetch ref advertisement from ${url}`, response.status);
+			assertContentType(response.headers.get("content-type") ?? "", RECEIVE_PACK_ADVERTISE_CONTENT_TYPE, url);
+			const data = await readResponseBody(response, url);
+			try {
+				return parseRefAdvertisement(data, RECEIVE_PACK_ADVERTISE_SERVICE);
+			} catch (err) {
+				if (err instanceof RefAdvertisementError) throw err;
+				throw new SmartHttpError(`Failed to parse ref advertisement: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		},
+		async request(body) {
+			const url = `${normalizedUrl}${RECEIVE_PACK_RPC_PATH}`;
+			let response;
+			try {
+				response = await fetch(url, {
+					method: "POST",
+					headers: applyAuthHeaders({ "Content-Type": RECEIVE_PACK_RPC_CONTENT_TYPE }, auth),
+					body
+				});
+			} catch (err) {
+				throw new SmartHttpError(`Failed to POST RPC request to ${url}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			if (!response.ok) throw new SmartHttpError(`RPC request to ${url} failed`, response.status);
+			assertContentType(response.headers.get("content-type") ?? "", RECEIVE_PACK_RESULT_CONTENT_TYPE, url);
+			return readResponseBody(response, url);
+		}
+	};
+}
+//#endregion
+export { SmartHttpError, createReceivePackHttpClient };

package/dist/transport/client/receive-pack/push-error.d.mts

@@ -0,0 +1,23 @@
+import { GitError } from "../../../core/errors.mjs";
+import { PushRefUpdate } from "../../protocol/types.mjs";
+
+//#region src/transport/client/receive-pack/push-error.d.ts
+/**
+ * Push 操作错误
+ *
+ * 当服务端部分或全部拒绝更新时抛出。
+ * 即使抛出异常，`refUpdates` 属性仍会保留服务端返回的所有 ref 状态
+ * （包含成功和失败的），以便调用方在部分成功场景下做出相应处理。
+ */
+declare class PushError extends GitError {
+  /** 服务端返回的所有 ref 更新结果（包含成功和失败） */
+  refUpdates?: PushRefUpdate[];
+  /** 服务端返回的进度消息 */
+  progress?: string[];
+  constructor(message: string, extra?: {
+    refUpdates?: PushRefUpdate[];
+    progress?: string[];
+  });
+}
+//#endregion
+export { PushError };

package/dist/transport/client/receive-pack/push-error.mjs

@@ -0,0 +1,32 @@
+import { GitError } from "../../../core/errors.mjs";
+//#region src/transport/client/receive-pack/push-error.ts
+/**
+* Push 操作错误类型
+*
+* 当服务端部分或全部拒绝更新时抛出。
+* 即使抛出异常，`refUpdates` 属性仍会保留服务端返回的所有 ref 状态
+* （包含成功和失败的），以便调用方在部分成功场景下做出相应处理。
+*/
+/**
+* Push 操作错误
+*
+* 当服务端部分或全部拒绝更新时抛出。
+* 即使抛出异常，`refUpdates` 属性仍会保留服务端返回的所有 ref 状态
+* （包含成功和失败的），以便调用方在部分成功场景下做出相应处理。
+*/
+var PushError = class extends GitError {
+	/** 服务端返回的所有 ref 更新结果（包含成功和失败） */
+	refUpdates;
+	/** 服务端返回的进度消息 */
+	progress;
+	constructor(message, extra) {
+		super(`Push error: ${message}`);
+		this.name = "PushError";
+		if (extra) {
+			this.refUpdates = extra.refUpdates;
+			this.progress = extra.progress;
+		}
+	}
+};
+//#endregion
+export { PushError };

package/dist/transport/client/receive-pack/push-pack-plan.d.mts

@@ -0,0 +1,28 @@
+import { SHA1 } from "../../../core/types.mjs";
+import { ObjectDatabase } from "../../../core/types/odb.mjs";
+import { PushRefItem } from "./push-ref-plan.mjs";
+
+//#region src/transport/client/receive-pack/push-pack-plan.d.ts
+/**
+ * 合并 shallow 边界与各推送项的远端当前 tip，供预检与本地可达性遍历使用
+ */
+declare function mergePushBoundaries(shallowSet: Set<SHA1> | undefined, pushRefs: PushRefItem[]): Set<SHA1> | undefined;
+/**
+ * 计算需要发送到远端的对象集合
+ *
+ * 需要推送的对象 = 从推送 refs 可达的对象 - 从远程已有 refs 可达的对象
+ * 删除操作（localHash === null）跳过对象收集。
+ *
+ * 本地可达性使用 "skip-commit-parents" 模式让缺失的 commit parent 不阻断遍历，
+ * 但 tree/blob/tag 等非 commit-parent 边的缺失仍会抛出 PushError。
+ *
+ * @param store - 本地对象存储
+ * @param pushRefs - 推送引用项列表
+ * @param remoteRefs - 远程 ref → hash 映射
+ * @param pushBoundaries - 合并后的边界集（可选）
+ * @returns 需要发送的对象哈希列表
+ * @throws PushError 当本地对象损坏导致无法遍历时
+ */
+declare function computeObjectsToSend(store: ObjectDatabase, pushRefs: PushRefItem[], remoteRefs: Map<string, SHA1>, pushBoundaries: Set<SHA1> | undefined): SHA1[];
+//#endregion
+export { computeObjectsToSend, mergePushBoundaries };

package/dist/transport/client/receive-pack/push-pack-plan.mjs

@@ -0,0 +1,60 @@
+import { collectReachable } from "../../protocol/object-graph.mjs";
+import { PushError } from "./push-error.mjs";
+//#region src/transport/client/receive-pack/push-pack-plan.ts
+/**
+* Push Pack 规划
+*
+* 处理"我要发送哪些对象"的问题：
+* - 合并 shallow 边界与远端 tip 边界
+* - 计算本地推送 ref 可达且远程缺失的对象差集
+*
+* @example
+* ```ts
+* import { mergePushBoundaries, computeObjectsToSend } from "./push-pack-plan.ts";
+* const boundaries = mergePushBoundaries(shallowSet, pushRefs);
+* const objectsToSend = computeObjectsToSend(store, pushRefs, remoteRefs, boundaries);
+* ```
+*/
+/**
+* 合并 shallow 边界与各推送项的远端当前 tip，供预检与本地可达性遍历使用
+*/
+function mergePushBoundaries(shallowSet, pushRefs) {
+	const remoteTips = pushRefs.map((item) => item.remoteHash).filter((hash) => hash !== null);
+	if (!shallowSet && remoteTips.length === 0) return;
+	const merged = new Set(shallowSet);
+	for (const hash of remoteTips) merged.add(hash);
+	return merged;
+}
+/**
+* 计算需要发送到远端的对象集合
+*
+* 需要推送的对象 = 从推送 refs 可达的对象 - 从远程已有 refs 可达的对象
+* 删除操作（localHash === null）跳过对象收集。
+*
+* 本地可达性使用 "skip-commit-parents" 模式让缺失的 commit parent 不阻断遍历，
+* 但 tree/blob/tag 等非 commit-parent 边的缺失仍会抛出 PushError。
+*
+* @param store - 本地对象存储
+* @param pushRefs - 推送引用项列表
+* @param remoteRefs - 远程 ref → hash 映射
+* @param pushBoundaries - 合并后的边界集（可选）
+* @returns 需要发送的对象哈希列表
+* @throws PushError 当本地对象损坏导致无法遍历时
+*/
+function computeObjectsToSend(store, pushRefs, remoteRefs, pushBoundaries) {
+	const localRoots = pushRefs.filter((r) => r.localHash !== null).map((r) => r.localHash);
+	let reachableLocal;
+	try {
+		reachableLocal = collectReachable(store, localRoots, "skip-commit-parents", pushBoundaries);
+	} catch (err) {
+		throw new PushError(err instanceof Error ? err.message : String(err));
+	}
+	const remoteRoots = [];
+	for (const [, hash] of remoteRefs) remoteRoots.push(hash);
+	const reachableRemote = collectReachable(store, remoteRoots);
+	const objectsToSend = [];
+	for (const hash of reachableLocal) if (!reachableRemote.has(hash)) objectsToSend.push(hash);
+	return objectsToSend;
+}
+//#endregion
+export { computeObjectsToSend, mergePushBoundaries };

package/dist/transport/client/receive-pack/push-policy.d.mts

@@ -0,0 +1,19 @@
+import { SHA1 } from "../../../core/types.mjs";
+import { ObjectDatabase } from "../../../core/types/odb.mjs";
+import { PushRefItem } from "./push-ref-plan.mjs";
+
+//#region src/transport/client/receive-pack/push-policy.d.ts
+/**
+ * 预检所有推送项是否为 fast-forward，不通过的（且未设 force）立即报错
+ *
+ * @param store - 对象存储
+ * @param items - 推送引用项列表
+ * @param shallowBoundaries - 已知 shallow 边界集合（可选）
+ *   提供后，isAncestor 会优先判断缺失 parent 是否为已知 shallow boundary，
+ *   避免在 shallow 仓库中将正常边界缺失误判为损坏。
+ *
+ * @throws PushError 如果存在 non-fast-forward 更新且未设 force
+ */
+declare function checkFastForward(store: ObjectDatabase, items: PushRefItem[], shallowBoundaries?: Set<SHA1>): void;
+//#endregion
+export { checkFastForward };

package/dist/transport/client/receive-pack/push-policy.mjs

@@ -0,0 +1,64 @@
+import { isAncestor, peelTagChain } from "../../protocol/object-graph.mjs";
+import { PushError } from "./push-error.mjs";
+//#region src/transport/client/receive-pack/push-policy.ts
+/**
+* Push 策略规则
+*
+* 处理"这些 ref 更新是否合法"的问题：
+* - fast-forward 预检
+* - refs/tags/* 更新限制
+* - non-commit 对象推送限制
+*
+* 纯规则层，不依赖协议细节。
+*
+* @example
+* ```ts
+* import { checkFastForward } from "./push-policy.ts";
+* const items = [{
+*   localRef: "refs/heads/main",
+*   remoteRef: "refs/heads/main",
+*   localHash: sha1("new"),
+*   remoteHash: sha1("old"),
+*   force: false,
+* }];
+* checkFastForward(store, items);
+* ```
+*/
+/**
+* 预检所有推送项是否为 fast-forward，不通过的（且未设 force）立即报错
+*
+* @param store - 对象存储
+* @param items - 推送引用项列表
+* @param shallowBoundaries - 已知 shallow 边界集合（可选）
+*   提供后，isAncestor 会优先判断缺失 parent 是否为已知 shallow boundary，
+*   避免在 shallow 仓库中将正常边界缺失误判为损坏。
+*
+* @throws PushError 如果存在 non-fast-forward 更新且未设 force
+*/
+function checkFastForward(store, items, shallowBoundaries) {
+	for (const item of items) {
+		if (item.localHash === null || item.remoteHash === null) continue;
+		if (item.force) continue;
+		if (item.localHash === item.remoteHash) continue;
+		if (item.remoteRef.startsWith("refs/tags/")) throw new PushError(`Tag update rejected for "${item.remoteRef}": tag already exists, cannot replace without force (--force or +refspec).`);
+		const peeledRemote = peelTagChain(store, item.remoteHash, shallowBoundaries);
+		const peeledLocal = peelTagChain(store, item.localHash, shallowBoundaries);
+		{
+			const remoteObj = store.tryRead(peeledRemote);
+			if (remoteObj !== void 0 && remoteObj.type !== "commit") throw new PushError(`Update rejected for "${item.remoteRef}": remote object is a ${remoteObj.type}, expected commit. Use --force or +refspec to override.`);
+		}
+		{
+			const localObj = store.tryRead(peeledLocal);
+			if (localObj !== void 0 && localObj.type !== "commit") throw new PushError(`Update rejected for "${item.remoteRef}": local object is a ${localObj.type}, expected commit. Use --force or +refspec to override.`);
+		}
+		const refBoundaries = /* @__PURE__ */ new Set();
+		if (item.remoteHash) refBoundaries.add(item.remoteHash);
+		if (!isAncestor(store, item.remoteHash, item.localHash, refBoundaries)) {
+			const shortRemote = item.remoteHash.slice(0, 8);
+			const shortLocal = item.localHash.slice(0, 8);
+			throw new PushError(`Non-fast-forward update rejected for "${item.remoteRef}": remote ${shortRemote} is not an ancestor of local ${shortLocal}. Use force (--force or +refspec) to override.`);
+		}
+	}
+}
+//#endregion
+export { checkFastForward };

package/dist/transport/client/receive-pack/push-ref-plan.d.mts

@@ -0,0 +1,45 @@
+import { SHA1 } from "../../../core/types.mjs";
+import { RefStore } from "../../../core/types/refs.mjs";
+import { ParsedRefSpec } from "../../protocol/refspec.mjs";
+
+//#region src/transport/client/receive-pack/push-ref-plan.d.ts
+/**
+ * 要推送的引用项
+ */
+interface PushRefItem {
+  /** 本地引用名称（删除操作时为空字符串） */
+  localRef: string;
+  /** 远程目标引用名称 */
+  remoteRef: string;
+  /** 本地 ref 当前指向的哈希（null 表示删除远程引用） */
+  localHash: SHA1 | null;
+  /** 远程 ref 当前指向的哈希（null 表示新建） */
+  remoteHash: SHA1 | null;
+  /** 是否强制推送 */
+  force: boolean;
+}
+/**
+ * 生成默认 refspec
+ *
+ * 等价于 `git push <url>` 的默认行为：将当前分支推送到远端同名分支。
+ * - HEAD 指向 `refs/heads/<name>` 时，返回 `"HEAD:refs/heads/<name>"`
+ * - HEAD 为 detached 状态时，抛出 PushError
+ *
+ * @param refs - 本地引用存储
+ * @returns 形如 `"HEAD:refs/heads/<branch>"` 的 refspec
+ * @throws PushError 当 HEAD 处于 detached 状态时
+ */
+declare function resolveDefaultRefSpec(refs: RefStore): string;
+/**
+ * 解析 refspec 并确定要推送的引用列表
+ *
+ * 根据 refspec 匹配本地引用，并与远程引用对照。
+ *
+ * @param localRefs - 本地 ref → hash 映射
+ * @param remoteRefs - 远程 ref → hash 映射
+ * @param specs - 解析后的 refspec 列表
+ * @returns 要推送的引用项列表
+ */
+declare function determinePushRefs(localRefs: Map<string, SHA1>, remoteRefs: Map<string, SHA1>, specs: ParsedRefSpec[]): PushRefItem[];
+//#endregion
+export { PushRefItem, determinePushRefs, resolveDefaultRefSpec };

package/dist/transport/client/receive-pack/push-ref-plan.mjs

@@ -0,0 +1,108 @@
+import { HEAD_REF } from "../../../core/types/refs.mjs";
+import { resolveSymbolicRef } from "../../../refs/resolve.mjs";
+import { PushError } from "./push-error.mjs";
+//#region src/transport/client/receive-pack/push-ref-plan.ts
+/**
+* Push 引用规划
+*
+* 处理"我要推哪些 ref"的问题：
+* - 解析 refspec 为本地→远程的映射
+* - 确定要推送的引用项列表
+* - 处理通配符、精确匹配、删除操作和去重
+*
+* @example
+* ```ts
+* import { determinePushRefs } from "./push-ref-plan.ts";
+* import { parseRefSpec } from "../../protocol/refspec.ts";
+*
+* const localRefs = new Map([["refs/heads/main", "abc123..."]]);
+* const remoteRefs = new Map();
+* const specs = [parseRefSpec("refs/heads/main:refs/heads/main")];
+* const items = determinePushRefs(localRefs, remoteRefs, specs);
+* ```
+*/
+/**
+* 生成默认 refspec
+*
+* 等价于 `git push <url>` 的默认行为：将当前分支推送到远端同名分支。
+* - HEAD 指向 `refs/heads/<name>` 时，返回 `"HEAD:refs/heads/<name>"`
+* - HEAD 为 detached 状态时，抛出 PushError
+*
+* @param refs - 本地引用存储
+* @returns 形如 `"HEAD:refs/heads/<branch>"` 的 refspec
+* @throws PushError 当 HEAD 处于 detached 状态时
+*/
+function resolveDefaultRefSpec(refs) {
+	const target = resolveSymbolicRef(refs, HEAD_REF);
+	if (target === null) throw new PushError("HEAD is detached — cannot determine current branch. Specify a refspec explicitly (e.g. { refSpecs: [\"HEAD:refs/heads/main\"] })");
+	if (!target.startsWith("refs/heads/")) throw new PushError(`HEAD points to "${target}" which is not a branch. Specify a refspec explicitly when pushing from a non-branch ref.`);
+	return `HEAD:${target}`;
+}
+/**
+* 解析 refspec 并确定要推送的引用列表
+*
+* 根据 refspec 匹配本地引用，并与远程引用对照。
+*
+* @param localRefs - 本地 ref → hash 映射
+* @param remoteRefs - 远程 ref → hash 映射
+* @param specs - 解析后的 refspec 列表
+* @returns 要推送的引用项列表
+*/
+function determinePushRefs(localRefs, remoteRefs, specs) {
+	const items = [];
+	const seen = /* @__PURE__ */ new Map();
+	let hasUnmatchedWildcard = false;
+	for (const spec of specs) if (spec.isWildcard) {
+		let matchedAny = false;
+		for (const [localRef, localHash] of localRefs) {
+			if (!localRef.startsWith(spec.srcPattern)) continue;
+			matchedAny = true;
+			const suffix = localRef.slice(spec.srcPattern.length);
+			const remoteRef = `${spec.dstPattern}${suffix}`;
+			const existingSpec = seen.get(remoteRef);
+			if (existingSpec !== void 0) throw new PushError(`Conflicting push refspec: "${spec.srcPattern}*:${spec.dstPattern}*" maps to "${remoteRef}" which is also mapped by "${existingSpec}".`);
+			seen.set(remoteRef, `${spec.srcPattern}*:${spec.dstPattern}*`);
+			const remoteHash = remoteRefs.get(remoteRef) ?? null;
+			items.push({
+				localRef,
+				remoteRef,
+				localHash,
+				remoteHash,
+				force: spec.force
+			});
+		}
+		if (!matchedAny) hasUnmatchedWildcard = true;
+	} else if (spec.srcPattern === "") {
+		const remoteRef = spec.dstPattern;
+		const existingSpec = seen.get(remoteRef);
+		if (existingSpec !== void 0) throw new PushError(`Conflicting push refspec: ":${spec.dstPattern}" maps to "${remoteRef}" which is also mapped by "${existingSpec}".`);
+		seen.set(remoteRef, `:${spec.dstPattern}`);
+		const remoteHash = remoteRefs.get(remoteRef) ?? null;
+		items.push({
+			localRef: "",
+			remoteRef: spec.dstPattern,
+			localHash: null,
+			remoteHash,
+			force: spec.force
+		});
+	} else {
+		const remoteRef = spec.dstPattern;
+		const existingSpec = seen.get(remoteRef);
+		if (existingSpec !== void 0) throw new PushError(`Conflicting push refspec: "${spec.srcPattern}:${spec.dstPattern}" maps to "${remoteRef}" which is also mapped by "${existingSpec}".`);
+		seen.set(remoteRef, `${spec.srcPattern}:${spec.dstPattern}`);
+		const localHash = localRefs.get(spec.srcPattern) ?? null;
+		if (!localHash) throw new PushError(`Local ref not found: "${spec.srcPattern}" (specified in refspec "${spec.srcPattern}:${spec.dstPattern}")`);
+		const remoteHash = remoteRefs.get(remoteRef) ?? null;
+		items.push({
+			localRef: spec.srcPattern,
+			remoteRef,
+			localHash,
+			remoteHash,
+			force: spec.force
+		});
+	}
+	if (items.length === 0 && hasUnmatchedWildcard) throw new PushError("src refspec does not match any local ref");
+	return items;
+}
+//#endregion
+export { determinePushRefs, resolveDefaultRefSpec };

package/dist/transport/client/receive-pack/push-report.d.mts

@@ -0,0 +1,28 @@
+import { PushRefUpdate } from "../../protocol/types.mjs";
+import { PushRefItem } from "./push-ref-plan.mjs";
+import { ReceivePackCommand } from "./request.mjs";
+
+//#region src/transport/client/receive-pack/push-report.d.ts
+/**
+ * 校验并富化服务端返回的 report-status 结果
+ *
+ * 执行以下校验：
+ * 1. 空 refUpdates 检测（协议异常）
+ * 2. 状态行数量一致性校验
+ * 3. ref 名称集合完全匹配校验
+ * 4. 构建富化 refUpdates（补充 oldHash/newHash/forced）
+ * 5. 检查被拒绝的更新
+ *
+ * @param commands - 发送给服务端的 receive-pack 命令列表
+ * @param refUpdates - 服务端解析后的 ref 更新结果
+ * @param pushRefs - 推送引用项列表（用于关联命令与元信息）
+ * @param progress - 服务端返回的进度消息
+ * @returns 富化后的完整 push 结果
+ * @throws PushError 当校验失败或存在被拒绝的更新时
+ */
+declare function processPushReport(commands: ReceivePackCommand[], refUpdates: PushRefUpdate[], pushRefs: PushRefItem[], progress: string[]): {
+  refUpdates: PushRefUpdate[];
+  progress: string[];
+};
+//#endregion
+export { processPushReport };

package/dist/transport/client/receive-pack/push-report.mjs

@@ -0,0 +1,84 @@
+import { PushError } from "./push-error.mjs";
+//#region src/transport/client/receive-pack/push-report.ts
+/**
+* Push 响应报告校验
+*
+* 处理"服务端回复是否完整可信"的问题：
+* - receive-pack 返回结果的完整性校验
+* - 命令和 refUpdates 的对应关系校验
+* - enrichedUpdates 构建
+*
+* @example
+* ```ts
+* import { processPushReport } from "./push-report.ts";
+* import { PushError } from "./push-error.ts";
+*
+* try {
+*   const result = processPushReport(commands, refUpdates, pushRefs, progress);
+*   return result;
+* } catch (err) {
+*   if (err instanceof PushError && err.refUpdates) {
+*     // 部分成功场景
+*   }
+* }
+* ```
+*/
+/**
+* 校验并富化服务端返回的 report-status 结果
+*
+* 执行以下校验：
+* 1. 空 refUpdates 检测（协议异常）
+* 2. 状态行数量一致性校验
+* 3. ref 名称集合完全匹配校验
+* 4. 构建富化 refUpdates（补充 oldHash/newHash/forced）
+* 5. 检查被拒绝的更新
+*
+* @param commands - 发送给服务端的 receive-pack 命令列表
+* @param refUpdates - 服务端解析后的 ref 更新结果
+* @param pushRefs - 推送引用项列表（用于关联命令与元信息）
+* @param progress - 服务端返回的进度消息
+* @returns 富化后的完整 push 结果
+* @throws PushError 当校验失败或存在被拒绝的更新时
+*/
+function processPushReport(commands, refUpdates, pushRefs, progress) {
+	if (commands.length > 0 && refUpdates.length === 0) throw new PushError("Server returned no status updates for the push commands. This may indicate a protocol compatibility issue or a server-side parsing error.");
+	if (commands.length !== refUpdates.length) {
+		const receivedRefNames = new Set(refUpdates.map((u) => u.refName));
+		const missingRefs = commands.filter((c) => !receivedRefNames.has(c.refName));
+		throw new PushError(`Server returned incomplete status: expected ${commands.length} status line(s) but got ${refUpdates.length}. Missing status for: ${missingRefs.map((r) => r.refName).join(", ")}`);
+	}
+	const commandRefNames = new Set(commands.map((c) => c.refName));
+	const updateRefNames = new Set(refUpdates.map((u) => u.refName));
+	const unexpectedRefs = [...updateRefNames].filter((n) => !commandRefNames.has(n));
+	const missingRefs = [...commandRefNames].filter((n) => !updateRefNames.has(n));
+	if (unexpectedRefs.length > 0 || missingRefs.length > 0) {
+		const parts = [];
+		if (unexpectedRefs.length > 0) parts.push(`unexpected ref(s): ${unexpectedRefs.join(", ")}`);
+		if (missingRefs.length > 0) parts.push(`missing ref(s): ${missingRefs.join(", ")}`);
+		throw new PushError(`Server returned mismatched ref status: ${parts.join("; ")}`);
+	}
+	const pushRefMap = /* @__PURE__ */ new Map();
+	for (const item of pushRefs) pushRefMap.set(item.remoteRef, item);
+	const enrichedUpdates = refUpdates.map((u) => {
+		const matched = pushRefMap.get(u.refName);
+		return {
+			refName: u.refName,
+			oldHash: matched?.remoteHash ?? null,
+			newHash: matched?.localHash ?? null,
+			success: u.success,
+			error: u.error,
+			forced: matched?.force ?? false
+		};
+	});
+	const rejectedUpdates = enrichedUpdates.filter((u) => !u.success);
+	if (rejectedUpdates.length > 0) throw new PushError(`Remote server rejected the push: ${rejectedUpdates.map((u) => `${u.refName}: ${u.error ?? "unknown error"}`).join("; ")}`, {
+		refUpdates: enrichedUpdates,
+		progress
+	});
+	return {
+		refUpdates: enrichedUpdates,
+		progress
+	};
+}
+//#endregion
+export { processPushReport };

package/dist/transport/client/receive-pack/push-request-plan.mjs

@@ -0,0 +1,52 @@
+import { sha1 } from "../../../core/types.mjs";
+import { parseRefSpec } from "../../protocol/refspec.mjs";
+import { PushError } from "./push-error.mjs";
+import { resolveDefaultRefSpec } from "./push-ref-plan.mjs";
+import { PUSH_CAPABILITIES, extractCapabilities } from "../../protocol/transport-capabilities.mjs";
+import { buildReceivePackRequest } from "./request.mjs";
+//#region src/transport/client/receive-pack/push-request-plan.ts
+/**
+* push 请求规划
+*
+* refspec 归一化、能力校验、receive-pack 命令与请求 body 构造。
+*/
+/** 零哈希（表示新建引用或删除引用） */
+const ZERO_HASH = sha1("0000000000000000000000000000000000000000");
+/**
+* 解析并归一化 push refspec
+*/
+function resolvePushParsedSpecs(refs, options) {
+	const parsedSpecs = (options?.refSpecs ?? [resolveDefaultRefSpec(refs)]).map(parseRefSpec);
+	if (options?.force) return parsedSpecs.map((s) => ({
+		...s,
+		force: true
+	}));
+	return parsedSpecs;
+}
+/**
+* 校验 push 所需远端能力
+*/
+function validatePushCapabilities(advertisement, pushRefs) {
+	const caps = extractCapabilities(advertisement.capabilities, PUSH_CAPABILITIES);
+	if (!caps.includes("report-status")) throw new PushError("Remote server does not advertise 'report-status' capability. This client requires report-status to reliably determine push results. Please use a Git server that supports report-status.");
+	if (pushRefs.some((r) => r.localHash === null) && !caps.includes("delete-refs")) throw new PushError("Remote server does not advertise 'delete-refs' capability, but the push includes a delete ref operation.");
+	return caps;
+}
+/**
+* 由 push 引用项构造 receive-pack 命令
+*/
+function buildPushCommands(pushRefs) {
+	return pushRefs.map((r) => ({
+		oldHash: r.remoteHash ?? ZERO_HASH,
+		newHash: r.localHash ?? ZERO_HASH,
+		refName: r.remoteRef
+	}));
+}
+/**
+* 构造 receive-pack 请求 body
+*/
+function buildPushRequestBody(commands, packfile, capabilities) {
+	return buildReceivePackRequest(commands, packfile, capabilities);
+}
+//#endregion
+export { buildPushCommands, buildPushRequestBody, resolvePushParsedSpecs, validatePushCapabilities };