nano-git 0.1.0

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

@@ -0,0 +1,32 @@
+import { RefStore } from "../../../core/types/refs.mjs";
+import { ObjectDatabase } from "../../../core/types/odb.mjs";
+import { PushOptions, PushResult, ReceivePackTransport, RefAdvertisement } from "../../protocol/types.mjs";
+import { PushError } from "./push-error.mjs";
+import { PushRefItem, determinePushRefs } from "./push-ref-plan.mjs";
+import { checkFastForward } from "./push-policy.mjs";
+
+//#region src/transport/client/receive-pack/push.d.ts
+/**
+ * 执行 push 操作
+ *
+ * 将本地对象推送到远程 Git 仓库。调用方需自行创建 ReceivePackTransport
+ * 并获取 advertisement。
+ *
+ * @param store - 本地对象存储
+ * @param refs - 本地引用存储
+ * @param transport - receive-pack 传输接口
+ * @param advertisement - 服务端 receive-pack 广告
+ * @param options - 可选配置（refSpecs、force、shallowBoundaries）
+ * @returns push 操作结果
+ *
+ * @example
+ * ```ts
+ * const transport = createReceivePackHttpClient("https://github.com/user/repo");
+ * const adv = await transport.advertise();
+ * const result = await push(store, refs, transport, adv, { refSpecs: [...] });
+ * console.log(`Pushed ${result.objectCount} objects`);
+ * ```
+ */
+declare function push(store: ObjectDatabase, refs: RefStore, transport: ReceivePackTransport, advertisement: RefAdvertisement, options?: PushOptions): Promise<PushResult>;
+//#endregion
+export { push };

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

@@ -0,0 +1,97 @@
+import { getLocalRefs, remoteRefsToMap } from "../../protocol/ref-collection.mjs";
+import { PushError } from "./push-error.mjs";
+import { createPackWriter } from "../../../pack/pack-writer.mjs";
+import { computeObjectsToSend, mergePushBoundaries } from "./push-pack-plan.mjs";
+import { checkFastForward } from "./push-policy.mjs";
+import { determinePushRefs } from "./push-ref-plan.mjs";
+import { processPushReport } from "./push-report.mjs";
+import { buildPushCommands, buildPushRequestBody, resolvePushParsedSpecs, validatePushCapabilities } from "./push-request-plan.mjs";
+import { ReceivePackResultError } from "./result.mjs";
+import { decodeReceivePackResponse } from "./response.mjs";
+//#region src/transport/client/receive-pack/push.ts
+/**
+* 高层 push 编排
+*
+* 编排完整的 Smart HTTP push 流程：
+* 1. 按 refspec 确定要推送的本地引用与远程目标
+* 2. 收集需要发送的对象
+* 3. 构建 packfile
+* 4. 构造 receive-pack 请求并发送
+* 5. 解析 report-status 响应
+*
+* push() 不再自行创建传输层或获取 advertisement ——
+* 这两种依赖由调用方通过 ReceivePackTransport + RefAdvertisement 显式传入。
+*
+* @example
+* ```ts
+* import { push } from "./transport/push.ts";
+*
+* const transport = createReceivePackHttpClient("https://github.com/user/repo");
+* const adv = await transport.advertise();
+* const result = await push(store, refs, transport, adv, { refSpecs: [...] });
+* console.log(`Pushed ${result.objectCount} objects`);
+* ```
+*/
+/**
+* 执行 push 操作
+*
+* 将本地对象推送到远程 Git 仓库。调用方需自行创建 ReceivePackTransport
+* 并获取 advertisement。
+*
+* @param store - 本地对象存储
+* @param refs - 本地引用存储
+* @param transport - receive-pack 传输接口
+* @param advertisement - 服务端 receive-pack 广告
+* @param options - 可选配置（refSpecs、force、shallowBoundaries）
+* @returns push 操作结果
+*
+* @example
+* ```ts
+* const transport = createReceivePackHttpClient("https://github.com/user/repo");
+* const adv = await transport.advertise();
+* const result = await push(store, refs, transport, adv, { refSpecs: [...] });
+* console.log(`Pushed ${result.objectCount} objects`);
+* ```
+*/
+async function push(store, refs, transport, advertisement, options) {
+	const effectiveSpecs = resolvePushParsedSpecs(refs, options);
+	const shallowSet = options?.shallowBoundaries ? new Set(options.shallowBoundaries) : void 0;
+	const localRefs = getLocalRefs(refs);
+	const remoteRefs = remoteRefsToMap(advertisement.refs);
+	const pushRefs = determinePushRefs(localRefs, remoteRefs, effectiveSpecs);
+	if (pushRefs.length === 0) return {
+		refUpdates: [],
+		objectCount: 0,
+		progress: []
+	};
+	const pushBoundaries = mergePushBoundaries(shallowSet, pushRefs);
+	checkFastForward(store, pushRefs, shallowSet);
+	const objectsToSend = computeObjectsToSend(store, pushRefs, remoteRefs, pushBoundaries);
+	const packWriter = createPackWriter();
+	for (const hash of objectsToSend) {
+		const raw = store.read(hash);
+		packWriter.addRaw(raw);
+	}
+	const packfile = packWriter.build();
+	const caps = validatePushCapabilities(advertisement, pushRefs);
+	const commands = buildPushCommands(pushRefs);
+	const body = buildPushRequestBody(commands, packfile, caps);
+	let progress;
+	let refUpdates;
+	try {
+		const decoded = decodeReceivePackResponse(await transport.request(body));
+		progress = decoded.progress;
+		refUpdates = decoded.refUpdates;
+	} catch (err) {
+		if (err instanceof ReceivePackResultError) throw new PushError(`Remote server rejected the push: ${err.message}`);
+		throw err;
+	}
+	const report = processPushReport(commands, refUpdates, pushRefs, progress);
+	return {
+		refUpdates: report.refUpdates,
+		objectCount: packWriter.objectCount,
+		progress: report.progress
+	};
+}
+//#endregion
+export { push };

package/dist/transport/client/receive-pack/request.d.mts

@@ -0,0 +1,39 @@
+import { SHA1 } from "../../../core/types.mjs";
+
+//#region src/transport/client/receive-pack/request.d.ts
+/**
+ * Receive-pack 引用更新命令
+ *
+ * 表示一条 push 命令：将远程的 refName 从 oldHash 更新为 newHash。
+ *
+ * - oldHash 为 000...0 表示新建引用
+ * - newHash 为 000...0 表示删除引用
+ */
+interface ReceivePackCommand {
+  /** 引用当前指向的哈希（服务端原有值） */
+  oldHash: SHA1;
+  /** 要更新到的目标哈希 */
+  newHash: SHA1;
+  /** 引用完整名称，如 "refs/heads/main" */
+  refName: string;
+}
+/**
+ * 构建 receive-pack 请求 body
+ *
+ * @param commands - 引用更新命令列表（至少一个）
+ * @param packfile - 包含新对象的 packfile 数据（push 时必需，delete 时可传空 Buffer）
+ * @param capabilities - 能力列表（如 ["report-status", "side-band-64k", "ofs-delta"]）
+ * @returns pkt-line 编码的请求 body Buffer
+ *
+ * @example
+ * ```ts
+ * const body = buildReceivePackRequest(
+ *   [{ oldHash: sha1("..."), newHash: sha1("..."), refName: "refs/heads/main" }],
+ *   packfile,
+ *   ["report-status", "side-band-64k", "ofs-delta"],
+ * );
+ * ```
+ */
+declare function buildReceivePackRequest(commands: ReceivePackCommand[], packfile: Buffer, capabilities: string[]): Buffer;
+//#endregion
+export { ReceivePackCommand, buildReceivePackRequest };

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

@@ -0,0 +1,46 @@
+import { encodeFlushPkt, encodePktLine } from "../../protocol/pkt-line.mjs";
+//#region src/transport/client/receive-pack/request.ts
+/**
+* 请求生成（receive-pack）
+*
+* 构造 Git receive-pack 请求 body。
+*
+* 协议 v1 的请求格式：
+*   <old-hash> <new-hash> <ref-name>\0<capabilities>\n    （首行带 capabilities）
+*   <old-hash> <new-hash> <ref-name>\n                     （后续命令）
+*   0000                                                     （flush）
+*   <packfile data>                                          （包数据，不经过 pkt-line 编码）
+*
+* @see https://git-scm.com/docs/git-receive-pack#_request
+*/
+/**
+* 构建 receive-pack 请求 body
+*
+* @param commands - 引用更新命令列表（至少一个）
+* @param packfile - 包含新对象的 packfile 数据（push 时必需，delete 时可传空 Buffer）
+* @param capabilities - 能力列表（如 ["report-status", "side-band-64k", "ofs-delta"]）
+* @returns pkt-line 编码的请求 body Buffer
+*
+* @example
+* ```ts
+* const body = buildReceivePackRequest(
+*   [{ oldHash: sha1("..."), newHash: sha1("..."), refName: "refs/heads/main" }],
+*   packfile,
+*   ["report-status", "side-band-64k", "ofs-delta"],
+* );
+* ```
+*/
+function buildReceivePackRequest(commands, packfile, capabilities) {
+	if (commands.length === 0) throw new Error("At least one command is required");
+	const chunks = [];
+	for (let i = 0; i < commands.length; i++) {
+		const cmd = commands[i];
+		if (i === 0 && capabilities.length > 0) chunks.push(encodePktLine(`${cmd.oldHash} ${cmd.newHash} ${cmd.refName}\0${capabilities.join(" ")}\n`));
+		else chunks.push(encodePktLine(`${cmd.oldHash} ${cmd.newHash} ${cmd.refName}\n`));
+	}
+	chunks.push(encodeFlushPkt());
+	if (packfile.length > 0) chunks.push(packfile);
+	return Buffer.concat(chunks);
+}
+//#endregion
+export { buildReceivePackRequest };

package/dist/transport/client/receive-pack/response.d.mts

@@ -0,0 +1,26 @@
+import { GitError } from "../../../core/errors.mjs";
+import { PushRefUpdate } from "../../protocol/types.mjs";
+
+//#region src/transport/client/receive-pack/response.d.ts
+/**
+ * receive-pack 响应解码错误
+ */
+declare class ReceivePackResponseError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 解码后的 receive-pack 响应
+ */
+interface DecodedReceivePackResponse {
+  readonly data: Buffer;
+  readonly refUpdates: PushRefUpdate[];
+  readonly progress: string[];
+}
+/**
+ * 解码 receive-pack RPC 原始响应
+ *
+ * @param data - transport.request() 返回的原始 body
+ */
+declare function decodeReceivePackResponse(data: Buffer): DecodedReceivePackResponse;
+//#endregion
+export { ReceivePackResponseError, decodeReceivePackResponse };

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

@@ -0,0 +1,52 @@
+import { GitError } from "../../../core/errors.mjs";
+import { parsePktLines } from "../../protocol/pkt-line.mjs";
+import { parseReceivePackResult } from "./result.mjs";
+//#region src/transport/client/receive-pack/response.ts
+/**
+* receive-pack 响应协议解码
+*
+* 从 transport 返回的原始 HTTP body 中解析 side-band 与 report-status。
+*/
+/**
+* receive-pack 响应解码错误
+*/
+var ReceivePackResponseError = class extends GitError {
+	constructor(message) {
+		super(`receive-pack response: ${message}`);
+		this.name = "ReceivePackResponseError";
+	}
+};
+/**
+* 解码 receive-pack RPC 原始响应
+*
+* @param data - transport.request() 返回的原始 body
+*/
+function decodeReceivePackResponse(data) {
+	let progress = [];
+	let refUpdates = [];
+	const pktLines = parsePktLines(data);
+	if (pktLines.length > 0 && pktLines[0].type === "data") {
+		const firstPayload = pktLines[0].payload;
+		if (firstPayload.length > 0 && (firstPayload[0] === 1 || firstPayload[0] === 2 || firstPayload[0] === 3)) {
+			const reportStatusChunks = [];
+			for (const line of pktLines) {
+				if (line.type !== "data") continue;
+				const payload = line.payload;
+				if (payload.length < 2) continue;
+				const channel = payload[0];
+				const frameData = payload.subarray(1);
+				if (channel === 1) reportStatusChunks.push(frameData);
+				else if (channel === 2) progress.push(frameData.toString("utf-8").trimEnd());
+				else if (channel === 3) throw new ReceivePackResponseError(`Server reported error: ${frameData.toString("utf-8").trimEnd()}`);
+			}
+			if (reportStatusChunks.length > 0) refUpdates = parseReceivePackResult(Buffer.concat(reportStatusChunks));
+		} else refUpdates = parseReceivePackResult(data);
+	}
+	return {
+		data,
+		refUpdates,
+		progress
+	};
+}
+//#endregion
+export { ReceivePackResponseError, decodeReceivePackResponse };

package/dist/transport/client/receive-pack/result.d.mts

@@ -0,0 +1,34 @@
+import { GitError } from "../../../core/errors.mjs";
+import { PushRefUpdate } from "../../protocol/types.mjs";
+
+//#region src/transport/client/receive-pack/result.d.ts
+/**
+ * Receive-pack 结果解析错误
+ *
+ * 当 report-status 数据格式不符合 Git 协议规范时抛出。
+ */
+declare class ReceivePackResultError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 从 receive-pack 响应中解析 report-status
+ *
+ * 输入数据应为已经过 side-band 解复用后的纯 pkt-line report-status 数据。
+ * 如果响应是 side-band 编码的，需要先调用 `extractPackfile`/`extractProgress`
+ * 再使用本函数解析 report-status 部分（在 side-band 中 report-status 位于
+ * channel 1 的 packfile 数据末尾的 pkt-line 中）。
+ *
+ * @param data - 来自服务端的 report-status 响应体（pkt-line 编码）
+ * @returns 解析后的引用更新状态列表，每个条目标明成功/失败及错误消息
+ *
+ * @example
+ * ```ts
+ * const result = parseReceivePackResult(responseBody);
+ * for (const update of result) {
+ *   console.log(`${update.refName}: ${update.success ? "OK" : "FAIL: " + update.error}`);
+ * }
+ * ```
+ */
+declare function parseReceivePackResult(data: Buffer): PushRefUpdate[];
+//#endregion
+export { ReceivePackResultError, parseReceivePackResult };

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

@@ -0,0 +1,100 @@
+import { GitError } from "../../../core/errors.mjs";
+import { parsePktLines } from "../../protocol/pkt-line.mjs";
+//#region src/transport/client/receive-pack/result.ts
+/**
+* 响应解析（receive-pack）
+*
+* 解析 `git-receive-pack` 返回的 report-status 响应。
+*
+* report-status 格式：
+*   <status-line>\n
+*   ...
+*   0000
+*
+* 每条 status-line：
+*   ok <ref-name>
+*   ng <ref-name> <error-msg>
+*
+* @see https://git-scm.com/docs/pack-protocol#_report_status
+*/
+/**
+* Receive-pack 结果解析错误
+*
+* 当 report-status 数据格式不符合 Git 协议规范时抛出。
+*/
+var ReceivePackResultError = class extends GitError {
+	constructor(message) {
+		super(`receive-pack result error: ${message}`);
+		this.name = "ReceivePackResultError";
+	}
+};
+/** report-status 中的 "ok" 前缀 */
+const OK_PREFIX = "ok ";
+/** report-status 中的 "ng" 前缀 */
+const NG_PREFIX = "ng ";
+/**
+* 从 receive-pack 响应中解析 report-status
+*
+* 输入数据应为已经过 side-band 解复用后的纯 pkt-line report-status 数据。
+* 如果响应是 side-band 编码的，需要先调用 `extractPackfile`/`extractProgress`
+* 再使用本函数解析 report-status 部分（在 side-band 中 report-status 位于
+* channel 1 的 packfile 数据末尾的 pkt-line 中）。
+*
+* @param data - 来自服务端的 report-status 响应体（pkt-line 编码）
+* @returns 解析后的引用更新状态列表，每个条目标明成功/失败及错误消息
+*
+* @example
+* ```ts
+* const result = parseReceivePackResult(responseBody);
+* for (const update of result) {
+*   console.log(`${update.refName}: ${update.success ? "OK" : "FAIL: " + update.error}`);
+* }
+* ```
+*/
+function parseReceivePackResult(data) {
+	const pktLines = parsePktLines(data);
+	const updates = [];
+	let seenUnpack = false;
+	for (const line of pktLines) {
+		if (line.type !== "data") continue;
+		const payload = line.payload.toString("utf-8").trimEnd();
+		if (payload.length === 0) continue;
+		if (!seenUnpack) {
+			if (payload.startsWith("unpack ")) {
+				seenUnpack = true;
+				const unpackResult = payload.slice(7);
+				if (unpackResult !== "ok") throw new ReceivePackResultError(`Server failed to unpack packfile: ${unpackResult}`);
+				continue;
+			}
+			throw new ReceivePackResultError(`Missing unpack status line: first status line is "${payload}", expected "unpack <result>"`);
+		}
+		if (payload.startsWith(OK_PREFIX)) {
+			const refName = payload.slice(3);
+			updates.push({
+				refName,
+				oldHash: null,
+				newHash: null,
+				success: true,
+				forced: false
+			});
+		} else if (payload.startsWith(NG_PREFIX)) {
+			const rest = payload.slice(3);
+			const spaceIndex = rest.indexOf(" ");
+			if (spaceIndex === -1) throw new ReceivePackResultError(`Invalid ng status line: "${payload}" (missing error message)`);
+			const refName = rest.substring(0, spaceIndex);
+			const errorMsg = rest.substring(spaceIndex + 1);
+			updates.push({
+				refName,
+				oldHash: null,
+				newHash: null,
+				success: false,
+				error: errorMsg,
+				forced: false
+			});
+		} else if (payload.startsWith("unpack ")) throw new ReceivePackResultError(`Unexpected duplicate unpack status line: "${payload}"`);
+		else throw new ReceivePackResultError(`Unexpected status line: "${payload}" (expected "ok " or "ng ")`);
+	}
+	return updates;
+}
+//#endregion
+export { ReceivePackResultError, parseReceivePackResult };

package/dist/transport/client/upload-pack/capability-advertisement.d.mts

@@ -0,0 +1,56 @@
+import { GitError } from "../../../core/errors.mjs";
+import { V2CapabilityAdvertisement } from "./types.mjs";
+
+//#region src/transport/client/upload-pack/capability-advertisement.d.ts
+/**
+ * v2 能力广告解析错误
+ */
+declare class V2CapabilityError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 解析 v2 能力广告响应
+ *
+ * @param data - 服务端返回的原始响应数据
+ * @returns 结构化的能力广告
+ * @throws {V2CapabilityError} 当格式不符合 v2 规范时
+ *
+ * @example
+ * ```ts
+ * const adv = parseV2CapabilityAdvertisement(response);
+ * console.log(adv.commands); // [{ name: "ls-refs", features: [] }, ...]
+ * console.log(adv.agent); // "nano-git/0.1"
+ * ```
+ */
+declare function parseV2CapabilityAdvertisement(data: Buffer): V2CapabilityAdvertisement;
+/**
+ * 检测 v2 能力广告中是否包含指定命令
+ *
+ * @param advertisement - v2 能力广告
+ * @param command - 命令名称
+ * @returns 是否支持
+ *
+ * @example
+ * ```ts
+ * if (hasCommand(adv, "ls-refs")) {
+ *   // 使用 ls-refs 获取 refs
+ * }
+ * ```
+ */
+declare function hasCommand(advertisement: V2CapabilityAdvertisement, command: string): boolean;
+/**
+ * 获取命令的附加特性列表
+ *
+ * @param advertisement - v2 能力广告
+ * @param command - 命令名称
+ * @returns 特性列表，命令不存在时返回空数组
+ *
+ * @example
+ * ```ts
+ * const fetchFeatures = getCommandFeatures(adv, "fetch");
+ * // ["shallow", "ref-in-want"]
+ * ```
+ */
+declare function getCommandFeatures(advertisement: V2CapabilityAdvertisement, command: string): string[];
+//#endregion
+export { V2CapabilityError, getCommandFeatures, hasCommand, parseV2CapabilityAdvertisement };

package/dist/transport/client/upload-pack/capability-advertisement.mjs

@@ -0,0 +1,130 @@
+import { GitError } from "../../../core/errors.mjs";
+import { parsePktLines } from "../../protocol/pkt-line.mjs";
+//#region src/transport/client/upload-pack/capability-advertisement.ts
+/**
+* v2 能力广告解析
+*
+* 解析 Git Wire 协议 v2 的 capability advertisement 响应。
+*
+* v2 能力广告格式：
+* ```
+* 000eversion 2\n
+* ls-refs\n
+* fetch=shallow ref-in-want\n
+* push\n
+* object-info\n
+* agent=nano-git/0.1\n
+* 0000
+* ```
+*
+* @see https://git-scm.com/docs/protocol-v2#_capability_advertisement
+*/
+/**
+* v2 能力广告解析错误
+*/
+var V2CapabilityError = class extends GitError {
+	constructor(message) {
+		super(`v2 capability error: ${message}`);
+		this.name = "V2CapabilityError";
+	}
+};
+/**
+* 解析 v2 能力广告响应
+*
+* @param data - 服务端返回的原始响应数据
+* @returns 结构化的能力广告
+* @throws {V2CapabilityError} 当格式不符合 v2 规范时
+*
+* @example
+* ```ts
+* const adv = parseV2CapabilityAdvertisement(response);
+* console.log(adv.commands); // [{ name: "ls-refs", features: [] }, ...]
+* console.log(adv.agent); // "nano-git/0.1"
+* ```
+*/
+function parseV2CapabilityAdvertisement(data) {
+	const lines = parsePktLines(data);
+	if (lines.length === 0) throw new V2CapabilityError("Empty capability advertisement");
+	const firstLine = lines[0];
+	if (!firstLine || firstLine.type !== "data") throw new V2CapabilityError(`Expected data line as first line, got ${firstLine?.type ?? "undefined"}`);
+	const versionStr = firstLine.payload.toString("utf-8").trim();
+	if (versionStr !== "version 2") throw new V2CapabilityError(`Expected "version 2", got "${versionStr}"`);
+	const capabilities = {};
+	const commands = [];
+	for (let i = 1; i < lines.length; i++) {
+		const line = lines[i];
+		if (!line || line.type !== "data") break;
+		const text = line.payload.toString("utf-8").trim();
+		if (text.length === 0) continue;
+		if ([
+			"ls-refs",
+			"fetch",
+			"object-info"
+		].some((cmd) => text.startsWith(cmd))) {
+			const eqIndex = text.indexOf("=");
+			if (eqIndex === -1) {
+				const name = text;
+				commands.push({
+					name,
+					features: []
+				});
+				capabilities[name] = true;
+			} else {
+				const name = text.substring(0, eqIndex);
+				const features = text.substring(eqIndex + 1).split(" ").filter((f) => f.length > 0);
+				commands.push({
+					name,
+					features
+				});
+				capabilities[name] = features.join(" ");
+			}
+		} else {
+			const eqIndex = text.indexOf("=");
+			if (eqIndex === -1) capabilities[text] = true;
+			else {
+				const key = text.substring(0, eqIndex);
+				capabilities[key] = text.substring(eqIndex + 1);
+			}
+		}
+	}
+	return {
+		capabilities,
+		commands,
+		agent: typeof capabilities.agent === "string" ? capabilities.agent : void 0
+	};
+}
+/**
+* 检测 v2 能力广告中是否包含指定命令
+*
+* @param advertisement - v2 能力广告
+* @param command - 命令名称
+* @returns 是否支持
+*
+* @example
+* ```ts
+* if (hasCommand(adv, "ls-refs")) {
+*   // 使用 ls-refs 获取 refs
+* }
+* ```
+*/
+function hasCommand(advertisement, command) {
+	return advertisement.commands.some((cmd) => cmd.name === command);
+}
+/**
+* 获取命令的附加特性列表
+*
+* @param advertisement - v2 能力广告
+* @param command - 命令名称
+* @returns 特性列表，命令不存在时返回空数组
+*
+* @example
+* ```ts
+* const fetchFeatures = getCommandFeatures(adv, "fetch");
+* // ["shallow", "ref-in-want"]
+* ```
+*/
+function getCommandFeatures(advertisement, command) {
+	return advertisement.commands.find((cmd) => cmd.name === command)?.features ?? [];
+}
+//#endregion
+export { V2CapabilityError, getCommandFeatures, hasCommand, parseV2CapabilityAdvertisement };