nano-git 0.1.0

package/dist/transport/protocol/side-band.d.mts

@@ -0,0 +1,65 @@
+import { GitError } from "../../core/errors.mjs";
+
+//#region src/transport/protocol/side-band.d.ts
+/**
+ * side-band 协议错误
+ *
+ * 当 side-band 数据格式不符合 Git 协议规范时抛出。
+ */
+declare class SideBandError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 从 side-band 编码的响应数据中提取 packfile
+ *
+ * 将 channel 1 的所有帧拼接为完整的 packfile buffer。
+ *
+ * @param data - 包含 side-band pkt-line 帧的完整响应数据
+ * @returns 拼接后的 packfile buffer
+ *
+ * @example
+ * ```ts
+ * const packfile = extractPackfile(responseData);
+ * const reader = createPackReader(packfile);
+ * ```
+ */
+declare function extractPackfile(data: Buffer): Buffer;
+/**
+ * 从 side-band 编码的响应数据中提取进度消息
+ *
+ * 收集 channel 2 的所有消息。
+ *
+ * @param data - 包含 side-band pkt-line 帧的完整响应数据
+ * @returns 进度消息列表
+ *
+ * @example
+ * ```ts
+ * const messages = extractProgress(responseData);
+ * console.log(messages);
+ * // [ "Receiving objects:  10% (1/10)", ... ]
+ * ```
+ */
+declare function extractProgress(data: Buffer): string[];
+/**
+ * 从非 side-band 编码的响应中提取原始 packfile 数据
+ *
+ * Git 协议中，若未协商 side-band-64k，upload-pack 的响应格式为：
+ * `<pkt-line 头部（NAK/ACK）> + <原始 packfile 数据>`。
+ * 此函数解析头部 pkt-lines，将剩余原始数据作为 packfile 返回。
+ *
+ * @param data - 非 side-band 响应的完整数据
+ * @returns 原始 packfile buffer
+ * @throws {SideBandError} 当尾部无 packfile 数据时
+ *
+ * @example
+ * ```ts
+ * const response = Buffer.concat([
+ *   encodePktLine("NAK\n"),
+ *   rawPackfileData,
+ * ]);
+ * const packfile = extractRawPackfile(response);
+ * ```
+ */
+declare function extractRawPackfile(data: Buffer): Buffer;
+//#endregion
+export { SideBandError, extractPackfile, extractProgress, extractRawPackfile };

package/dist/transport/protocol/side-band.mjs

@@ -0,0 +1,142 @@
+import { GitError } from "../../core/errors.mjs";
+import { parsePktLines, splitPktLinesFromBuffer } from "./pkt-line.mjs";
+//#region src/transport/protocol/side-band.ts
+/**
+* side-band 多路解复用
+*
+* Git 协议使用 side-band 在单一连接上多路传输数据。
+* side-band-64k 将数据分割为 pkt-line 帧，每帧第一个字节为 channel 编号。
+*
+* Channel 约定：
+* - 0x01: packfile 数据（需拼接为完整 packfile）
+* - 0x02: 进度消息（可用于显示传输进度）
+* - 0x03: 致命错误（传输过程中出错）
+*
+* @see https://git-scm.com/docs/pack-protocol#_side_channel
+*/
+/** side-band channel 编号 */
+const CHANNEL_PACKFILE = 1;
+const CHANNEL_PROGRESS = 2;
+const CHANNEL_FATAL = 3;
+/**
+* side-band 协议错误
+*
+* 当 side-band 数据格式不符合 Git 协议规范时抛出。
+*/
+var SideBandError = class extends GitError {
+	constructor(message) {
+		super(`side-band error: ${message}`);
+		this.name = "SideBandError";
+	}
+};
+/**
+* 从 side-band 编码的响应数据中提取 packfile
+*
+* 将 channel 1 的所有帧拼接为完整的 packfile buffer。
+*
+* @param data - 包含 side-band pkt-line 帧的完整响应数据
+* @returns 拼接后的 packfile buffer
+*
+* @example
+* ```ts
+* const packfile = extractPackfile(responseData);
+* const reader = createPackReader(packfile);
+* ```
+*/
+function extractPackfile(data) {
+	const chunks = [];
+	processSideBand(data, {
+		onPackfile(chunk) {
+			chunks.push(chunk);
+		},
+		onProgress() {},
+		onFatal(msg) {
+			throw new SideBandError(`Server reported fatal error: ${msg}`);
+		}
+	});
+	if (chunks.length === 0) throw new SideBandError("No packfile data found in side-band stream");
+	return Buffer.concat(chunks);
+}
+/**
+* 从 side-band 编码的响应数据中提取进度消息
+*
+* 收集 channel 2 的所有消息。
+*
+* @param data - 包含 side-band pkt-line 帧的完整响应数据
+* @returns 进度消息列表
+*
+* @example
+* ```ts
+* const messages = extractProgress(responseData);
+* console.log(messages);
+* // [ "Receiving objects:  10% (1/10)", ... ]
+* ```
+*/
+function extractProgress(data) {
+	const messages = [];
+	processSideBand(data, {
+		onPackfile() {},
+		onProgress(msg) {
+			messages.push(msg);
+		},
+		onFatal(msg) {
+			throw new SideBandError(`Server reported fatal error: ${msg}`);
+		}
+	});
+	return messages;
+}
+/**
+* 从非 side-band 编码的响应中提取原始 packfile 数据
+*
+* Git 协议中，若未协商 side-band-64k，upload-pack 的响应格式为：
+* `<pkt-line 头部（NAK/ACK）> + <原始 packfile 数据>`。
+* 此函数解析头部 pkt-lines，将剩余原始数据作为 packfile 返回。
+*
+* @param data - 非 side-band 响应的完整数据
+* @returns 原始 packfile buffer
+* @throws {SideBandError} 当尾部无 packfile 数据时
+*
+* @example
+* ```ts
+* const response = Buffer.concat([
+*   encodePktLine("NAK\n"),
+*   rawPackfileData,
+* ]);
+* const packfile = extractRawPackfile(response);
+* ```
+*/
+function extractRawPackfile(data) {
+	const { trailing } = splitPktLinesFromBuffer(data);
+	if (trailing.length === 0) throw new SideBandError("No packfile data found in non-side-band response");
+	return trailing;
+}
+/**
+* 处理 side-band 数据流
+*
+* 遍历所有 pkt-line 帧，根据 channel 编号分发到对应回调。
+*/
+function processSideBand(data, handlers) {
+	const pktLines = parsePktLines(data);
+	for (const line of pktLines) {
+		if (line.type !== "data") continue;
+		const payload = line.payload;
+		if (payload.length === 0) continue;
+		const channel = payload[0];
+		if (payload.length < 2) continue;
+		const content = payload.subarray(1);
+		switch (channel) {
+			case CHANNEL_PACKFILE:
+				handlers.onPackfile(content);
+				break;
+			case CHANNEL_PROGRESS:
+				handlers.onProgress(content.toString("utf-8"));
+				break;
+			case CHANNEL_FATAL:
+				handlers.onFatal(content.toString("utf-8"));
+				break;
+			default: break;
+		}
+	}
+}
+//#endregion
+export { SideBandError, extractPackfile, extractProgress, extractRawPackfile };

package/dist/transport/protocol/transport-capabilities.mjs

@@ -0,0 +1,46 @@
+//#region src/transport/protocol/transport-capabilities.ts
+/**
+* 传输层能力管理
+*
+* 处理 Git 协议中服务端能力声明与客户端可用能力的过滤。
+* 将 push/fetch 各自的能力白名单与共享的过滤逻辑合并。
+*
+* @example
+* ```ts
+* import { extractCapabilities, PUSH_CAPABILITIES } from "./transport-capabilities.ts";
+* const caps = extractCapabilities(serverCaps, PUSH_CAPABILITIES);
+* ```
+*/
+/** push (receive-pack) 默认支持的客户端能力 */
+const PUSH_CAPABILITIES = [
+	"report-status",
+	"side-band-64k",
+	"ofs-delta",
+	"no-progress",
+	"delete-refs"
+];
+/**
+* 从服务端 capabilities 中提取客户端可用的能力列表
+*
+* 将服务端声明的能力与客户端支持白名单取交集，
+* 只返回双方都支持的能力。
+*
+* @param serverCaps - 服务端声明的能力字典
+* @param supported - 客户端支持的能力白名单
+* @returns 双方都支持的能力名称列表
+*
+* @example
+* ```ts
+* const caps = extractCapabilities(
+*   { "report-status": true, "side-band-64k": true, "unknown-opt": "v1" },
+*   PUSH_CAPABILITIES,
+* );
+* // => ["report-status", "side-band-64k"]
+* ```
+*/
+function extractCapabilities(serverCaps, supported) {
+	const supportedSet = new Set(supported);
+	return Object.keys(serverCaps).filter((cap) => supportedSet.has(cap));
+}
+//#endregion
+export { PUSH_CAPABILITIES, extractCapabilities };

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

@@ -0,0 +1,148 @@
+import { SHA1 } from "../../core/types.mjs";
+
+//#region src/transport/protocol/types.d.ts
+/**
+ * Git 服务传输同构接口
+ *
+ * 只负责获取 ref 广告与发送 RPC body 并返回原始响应体。
+ */
+interface GitServiceTransport {
+  /** 获取 ref 广告（已解析为 RefAdvertisement，含 defaultBranch） */
+  advertise(): Promise<RefAdvertisement>;
+  /** 发送协议 RPC 请求，返回原始响应 body */
+  request(body: Buffer): Promise<Buffer>;
+}
+/**
+ * Receive-pack 传输接口（push）
+ */
+type ReceivePackTransport = GitServiceTransport;
+/**
+ * 远程引用
+ *
+ * 表示服务端广告的单个 Git 引用。
+ *
+ * @example
+ * ```ts
+ * const ref: RemoteRef = {
+ *   hash: sha1("95d09f2b10159347eece71399a7e2e907ea3df4f"),
+ *   name: "refs/heads/main",
+ * };
+ * ```
+ */
+interface RemoteRef {
+  /** 引用指向的对象哈希 */
+  hash: SHA1;
+  /** 引用完整名称，如 "refs/heads/main" */
+  name: string;
+  /** 如果引用是 annotated tag，此项为最终指向的 peeled 对象哈希 */
+  peeled?: SHA1;
+  /**
+   * 符号引用目标
+   * 如 "HEAD" → "refs/heads/main"
+   */
+  symrefTarget?: string;
+}
+/**
+ * 服务端引用广告
+ *
+ * 包含服务端通过 ref advertisement 响应的能力声明和所有引用。
+ *
+ * @example
+ * ```ts
+ * const adv: RefAdvertisement = {
+ *   capabilities: { multi_ack: true, "symref": "HEAD:refs/heads/main" },
+ *   refs: [ { hash: sha1("..."), name: "refs/heads/main" } ],
+ * };
+ * ```
+ */
+interface RefAdvertisement {
+  /** 服务端能力声明 */
+  capabilities: Record<string, string | true>;
+  /** 所有广告的引用列表 */
+  refs: RemoteRef[];
+  /**
+   * 远端默认分支（如 refs/heads/main）
+   * 由 parseRefAdvertisement 统一解析，调用方不得再读 capabilities.symref
+   */
+  defaultBranch?: string;
+}
+/**
+ * Ref 映射规则
+ */
+interface RefMappingRule {
+  readonly source: string;
+  readonly target: string;
+  readonly force?: boolean;
+}
+/**
+ * Ref 更新拒绝项
+ */
+interface RefUpdateRejection {
+  readonly localRef: string;
+  readonly reason: string;
+}
+/**
+ * 应用 ref 更新结果
+ */
+interface ApplyRefUpdatesResult {
+  readonly updatedRefs: Map<string, SHA1>;
+  readonly rejectedRefs: RefUpdateRejection[];
+}
+/**
+ * Push 操作选项
+ *
+ * 控制 push 行为。纯 push 参数，不含传输层细节（transport、token、headers 等）。
+ * 调用方需自行创建 ReceivePackTransport 并传入 push()。
+ */
+interface PushOptions {
+  /**
+   * refspec 列表，格式如 "refs/heads/main:refs/heads/main"
+   * 默认为将当前分支推送到远端同名分支（等价于 `git push <url>`）
+   */
+  refSpecs?: string[];
+  /** 是否强制推送（--force），等价于 refspec 的 + 前缀 */
+  force?: boolean;
+  /**
+   * 已知的 shallow 边界 commit 哈希列表
+   *
+   * 设置此字段后，push 在遍历本地 commit 图遇到边界缺失 parent 时，
+   * 会优先检查该哈希是否在 shallow 集合中：
+   * - 如果在，按 shallow boundary 处理（允许正常的边界缺失）
+   * - 如果不在，按本地损坏报错（避免误判）
+   *
+   * 通常由 Repository 层自动从 backend.shallow 读取，无需调用方手工设置。
+   */
+  shallowBoundaries?: SHA1[];
+}
+/**
+ * 单条引用更新结果
+ *
+ * 表示服务端对单个引用更新命令的响应。
+ */
+interface PushRefUpdate {
+  /** 引用名称，如 "refs/heads/main" */
+  refName: string;
+  /** 更新前的哈希（服务端原有值） */
+  oldHash: SHA1 | null;
+  /** 更新后的哈希 */
+  newHash: SHA1 | null;
+  /** 是否成功 */
+  success: boolean;
+  /** 失败时的错误消息 */
+  error?: string;
+  /** 是否强制更新 */
+  forced: boolean;
+}
+/**
+ * Push 操作结果
+ */
+interface PushResult {
+  /** 已更新的引用列表 */
+  refUpdates: PushRefUpdate[];
+  /** 推送的对象数量 */
+  objectCount: number;
+  /** 服务端推送的进度消息 */
+  progress: string[];
+}
+//#endregion
+export { ApplyRefUpdatesResult, GitServiceTransport, PushOptions, PushRefUpdate, PushResult, ReceivePackTransport, RefAdvertisement, RefMappingRule, RefUpdateRejection, RemoteRef };

package/dist/transport/protocol/update-refs.d.mts

@@ -0,0 +1,68 @@
+import { SHA1 } from "../../core/types.mjs";
+import { RefStore } from "../../core/types/refs.mjs";
+import { ObjectDatabase } from "../../core/types/odb.mjs";
+import { GitError } from "../../core/errors.mjs";
+import { ApplyRefUpdatesResult, RemoteRef } from "./types.mjs";
+
+//#region src/transport/protocol/update-refs.d.ts
+/**
+ * Ref 更新计划项
+ *
+ * 表示一个需要执行的本地 ref 写操作。
+ */
+interface RefUpdatePlanItem {
+  readonly remoteRef: RemoteRef;
+  readonly localRef: string;
+  readonly currentLocalHash?: SHA1;
+  readonly force: boolean;
+}
+/**
+ * Ref 更新错误
+ */
+declare class RefUpdateError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 校验远程 ref 对象可写入 refs/heads/*
+ *
+ * refs/heads/* 只能指向 commit 对象。
+ *
+ * @param store - 对象存储
+ * @param hash - 远程引用哈希
+ * @param refName - 远程引用名称（仅用于错误消息）
+ * @returns 可用于写入 refs/heads/* 的哈希
+ * @throws RefUpdateError 如果目标对象不存在或不是 commit
+ */
+declare function resolveBranchTargetHash(store: ObjectDatabase, hash: SHA1, refName: string): SHA1;
+/**
+ * 判断指定 ref 是否属于需要 fast-forward 检查的命名空间
+ *
+ * Git fetch 语义：仅 refs/heads/* 在没有 + 的 refspec 下要求新 tip 必须是
+ * 旧 tip 的子孙（快进）。
+ */
+declare function isRefNamespaceRequiringFastForward(refName: string): boolean;
+/**
+ * 应用 ref 更新
+ *
+ * 根据更新计划逐条应用 ref 更新，执行以下校验：
+ * - wanted tip 对象存在性校验
+ * - refs/heads/* 的 commit 类型校验
+ * - refs/tags/* 的非 force 拒绝替换
+ * - refs/heads/* 的非 force fast-forward 检查
+ *
+ * @param store - 对象存储（用于校验对象存在性和类型）
+ * @param refs - 本地引用存储
+ * @param updates - ref 更新计划项列表
+ * @returns 更新结果（成功和拒绝列表）
+ *
+ * @example
+ * ```ts
+ * const result = applyRefUpdates(objects, refs, plan.updates);
+ * for (const [ref, hash] of result.updatedRefs) {
+ *   console.log(`Updated ${ref} -> ${hash}`);
+ * }
+ * ```
+ */
+declare function applyRefUpdates(store: ObjectDatabase, refs: RefStore, updates: RefUpdatePlanItem[]): ApplyRefUpdatesResult;
+//#endregion
+export { RefUpdateError, applyRefUpdates, isRefNamespaceRequiringFastForward, resolveBranchTargetHash };

package/dist/transport/protocol/update-refs.mjs

@@ -0,0 +1,126 @@
+import { GitError } from "../../core/errors.mjs";
+import { tryReadObject } from "../../objects/raw.mjs";
+import { isAncestor } from "./object-graph.mjs";
+//#region src/transport/protocol/update-refs.ts
+/**
+* 应用本地 ref 更新
+*
+* 根据 RefUpdatePlanItem[] 应用 ref 更新，执行 fast-forward / tag / object-type 校验，
+* 返回成功更新与拒绝更新明细。
+*
+* @example
+* ```ts
+* const result = applyRefUpdates(store, refs, plan.updates);
+* console.log(`Updated ${result.updatedRefs.size} refs`);
+* ```
+*/
+/**
+* Ref 更新错误
+*/
+var RefUpdateError = class extends GitError {
+	constructor(message) {
+		super(`Ref update error: ${message}`);
+		this.name = "RefUpdateError";
+	}
+};
+/**
+* 校验远程 ref 对象可写入 refs/heads/*
+*
+* refs/heads/* 只能指向 commit 对象。
+*
+* @param store - 对象存储
+* @param hash - 远程引用哈希
+* @param refName - 远程引用名称（仅用于错误消息）
+* @returns 可用于写入 refs/heads/* 的哈希
+* @throws RefUpdateError 如果目标对象不存在或不是 commit
+*/
+function resolveBranchTargetHash(store, hash, refName) {
+	const obj = tryReadObject(store, hash);
+	if (obj === void 0) throw new RefUpdateError(`Object ${hash} for remote ref "${refName}" is missing from the local store. refs/heads/* can only point to commit objects.`);
+	if (obj.type === "tag") throw new RefUpdateError(`Remote ref "${refName}" (${hash}) is a tag object, expected commit. refs/heads/* can only point to commit objects.`);
+	if (obj.type !== "commit") throw new RefUpdateError(`Remote ref "${refName}" (${hash}) is a ${obj.type}, expected commit. refs/heads/* can only point to commit objects.`);
+	return hash;
+}
+/**
+* 判断指定 ref 是否属于需要 fast-forward 检查的命名空间
+*
+* Git fetch 语义：仅 refs/heads/* 在没有 + 的 refspec 下要求新 tip 必须是
+* 旧 tip 的子孙（快进）。
+*/
+function isRefNamespaceRequiringFastForward(refName) {
+	return refName.startsWith("refs/heads/");
+}
+/**
+* 应用 ref 更新
+*
+* 根据更新计划逐条应用 ref 更新，执行以下校验：
+* - wanted tip 对象存在性校验
+* - refs/heads/* 的 commit 类型校验
+* - refs/tags/* 的非 force 拒绝替换
+* - refs/heads/* 的非 force fast-forward 检查
+*
+* @param store - 对象存储（用于校验对象存在性和类型）
+* @param refs - 本地引用存储
+* @param updates - ref 更新计划项列表
+* @returns 更新结果（成功和拒绝列表）
+*
+* @example
+* ```ts
+* const result = applyRefUpdates(objects, refs, plan.updates);
+* for (const [ref, hash] of result.updatedRefs) {
+*   console.log(`Updated ${ref} -> ${hash}`);
+* }
+* ```
+*/
+function applyRefUpdates(store, refs, updates) {
+	const committedUpdates = [];
+	const rejectedRefs = [];
+	const rejectedSet = /* @__PURE__ */ new Set();
+	for (const item of updates) if (!store.exists(item.remoteRef.hash)) {
+		rejectedRefs.push({
+			localRef: item.localRef,
+			reason: `Object ${item.remoteRef.hash} was advertised but not received in the packfile`
+		});
+		rejectedSet.add(item.localRef);
+		continue;
+	}
+	for (const item of updates) {
+		const { remoteRef, localRef, currentLocalHash, force } = item;
+		if (rejectedSet.has(localRef)) continue;
+		const writeHash = localRef.startsWith("refs/heads/") ? resolveBranchTargetHash(store, remoteRef.hash, remoteRef.name) : remoteRef.hash;
+		if (!force && currentLocalHash !== void 0) {
+			if (localRef.startsWith("refs/tags/")) {
+				rejectedRefs.push({
+					localRef,
+					reason: `Tag "${localRef}" already exists and force is not set`
+				});
+				continue;
+			}
+			if (isRefNamespaceRequiringFastForward(localRef) && !isAncestor(store, currentLocalHash, writeHash)) {
+				rejectedRefs.push({
+					localRef,
+					reason: `Non-fast-forward update rejected for "${localRef}"`
+				});
+				continue;
+			}
+		}
+		committedUpdates.push({
+			localRef,
+			writeHash
+		});
+	}
+	const tx = refs.beginTransaction();
+	try {
+		for (const { localRef, writeHash } of committedUpdates) tx.write(localRef, writeHash);
+		tx.commit();
+	} catch (e) {
+		tx.rollback();
+		throw e;
+	}
+	return {
+		updatedRefs: new Map(committedUpdates.map((u) => [u.localRef, u.writeHash])),
+		rejectedRefs
+	};
+}
+//#endregion
+export { RefUpdateError, applyRefUpdates, isRefNamespaceRequiringFastForward, resolveBranchTargetHash };

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

@@ -0,0 +1,11 @@
+import { PushError } from "./client/receive-pack/push-error.mjs";
+import { PushRefItem, determinePushRefs, resolveDefaultRefSpec } from "./client/receive-pack/push-ref-plan.mjs";
+import { checkFastForward } from "./client/receive-pack/push-policy.mjs";
+import { push } from "./client/receive-pack/push.mjs";
+import { computeObjectsToSend, mergePushBoundaries } from "./client/receive-pack/push-pack-plan.mjs";
+import { ReceivePackCommand, buildReceivePackRequest } from "./client/receive-pack/request.mjs";
+import { processPushReport } from "./client/receive-pack/push-report.mjs";
+import { ReceivePackResultError, parseReceivePackResult } from "./client/receive-pack/result.mjs";
+import { ReceivePackResponseError, decodeReceivePackResponse } from "./client/receive-pack/response.mjs";
+import { SmartHttpAuth, SmartHttpError, createReceivePackHttpClient } from "./client/receive-pack/http.mjs";
+export { PushError, type PushRefItem, type ReceivePackCommand, ReceivePackResponseError, ReceivePackResultError, type SmartHttpAuth, SmartHttpError, buildReceivePackRequest, checkFastForward, computeObjectsToSend, createReceivePackHttpClient, decodeReceivePackResponse, determinePushRefs, mergePushBoundaries, parseReceivePackResult, processPushReport, push, resolveDefaultRefSpec };

package/dist/transport/receive-pack.mjs

@@ -0,0 +1,11 @@
+import { PushError } from "./client/receive-pack/push-error.mjs";
+import { SmartHttpError, createReceivePackHttpClient } from "./client/receive-pack/http.mjs";
+import { computeObjectsToSend, mergePushBoundaries } from "./client/receive-pack/push-pack-plan.mjs";
+import { checkFastForward } from "./client/receive-pack/push-policy.mjs";
+import { determinePushRefs, resolveDefaultRefSpec } from "./client/receive-pack/push-ref-plan.mjs";
+import { processPushReport } from "./client/receive-pack/push-report.mjs";
+import { buildReceivePackRequest } from "./client/receive-pack/request.mjs";
+import { ReceivePackResultError, parseReceivePackResult } from "./client/receive-pack/result.mjs";
+import { ReceivePackResponseError, decodeReceivePackResponse } from "./client/receive-pack/response.mjs";
+import { push } from "./client/receive-pack/push.mjs";
+export { PushError, ReceivePackResponseError, ReceivePackResultError, SmartHttpError, buildReceivePackRequest, checkFastForward, computeObjectsToSend, createReceivePackHttpClient, decodeReceivePackResponse, determinePushRefs, mergePushBoundaries, parseReceivePackResult, processPushReport, push, resolveDefaultRefSpec };

package/dist/transport/server/receive-pack/advertise.d.mts

@@ -0,0 +1,28 @@
+import { RepositoryBackend } from "../../../backend/types.mjs";
+
+//#region src/transport/server/receive-pack/advertise.d.ts
+/**
+ * 生成 receive-pack 的 ref 广告
+ *
+ * 格式：
+ * ```
+ * 001e# service=git-receive-pack\n
+ * 0000
+ * <length><hash> <refname>\0<capabilities>\n   ← 首行 ref 携带 capabilities
+ * <length><hash> <refname>\n                    ← 后续 ref
+ * ...
+ * 0000
+ * ```
+ *
+ * @param backend - 仓库后端
+ * @returns 完整 advertisement（pkt-line 编码）
+ *
+ * @example
+ * ```ts
+ * const buf = advertiseReceivePack(backend);
+ * // Response 的 Content-Type 应为 "application/x-git-receive-pack-advertisement"
+ * ```
+ */
+declare function advertiseReceivePack(backend: RepositoryBackend): Buffer;
+//#endregion
+export { advertiseReceivePack };