nano-git 0.1.0

package/dist/transport/client/upload-pack/fetch.d.mts

@@ -0,0 +1,109 @@
+import { ObjectDatabase } from "../../../core/types/odb.mjs";
+import { GitError } from "../../../core/errors.mjs";
+import { V2FetchResponse, V2GitServiceTransport } from "./types.mjs";
+
+//#region src/transport/client/upload-pack/fetch.d.ts
+/**
+ * v2 fetch 命令错误
+ */
+declare class V2FetchError extends GitError {
+  constructor(message: string);
+}
+/**
+ * v2 fetch 参数
+ *
+ * 对应 git protocol v2 fetch 命令的 arguments 段参数。
+ */
+interface V2FetchParams {
+  /** want 列表（对象哈希） */
+  readonly wants: string[];
+  /** have 列表（对象哈希） */
+  readonly haves?: string[];
+  /** 是否发送 done（结束协商，直接要求 packfile） */
+  readonly done?: boolean;
+  /** want-ref 列表（按 ref 名请求） */
+  readonly wantRefs?: string[];
+  /** 是否请求 thin-pack */
+  readonly thinPack?: boolean;
+  /** 是否禁用进度消息 */
+  readonly noProgress?: boolean;
+  /** 是否请求 include-tag */
+  readonly includeTag?: boolean;
+  /** 是否支持 ofs-delta */
+  readonly ofsDelta?: boolean;
+  /** shallow 边界 */
+  readonly shallow?: string[];
+  /** deepen 深度 */
+  readonly deepen?: number;
+  /** deepen-relative 标志 */
+  readonly deepenRelative?: boolean;
+  /** deepen-since 时间戳 */
+  readonly deepenSince?: number;
+  /** deepen-not 排除 */
+  readonly deepenNot?: string[];
+  /** filter 表达式 */
+  readonly filter?: string;
+  /** sideband-all 标志 */
+  readonly sidebandAll?: boolean;
+  /** wait-for-done 标志 */
+  readonly waitForDone?: boolean;
+}
+/**
+ * 执行 v2 fetch 命令
+ *
+ * 构建并发送 fetch 请求，返回解析后的完整响应。
+ *
+ * @param transport - v2 传输接口
+ * @param params - fetch 参数
+ * @param features - 服务端 fetch 命令支持的附加特性
+ * @returns 解析后的 fetch 响应
+ * @throws {V2FetchError} 当 wants 为空时
+ *
+ * @example
+ * ```ts
+ * const result = await v2Fetch(transport, {
+ *   wants: [hash1, hash2],
+ *   ofsDelta: true,
+ *   done: true,
+ * });
+ * console.log(result.packfile?.length); // packfile 数据长度
+ * ```
+ */
+declare function v2Fetch(transport: V2GitServiceTransport, params: V2FetchParams, features?: string[]): Promise<V2FetchResponse>;
+/**
+ * 解析 v2 fetch 响应
+ *
+ * v2 fetch 响应由多个节组成，节之间由 delimiter (0001) 分隔。
+ * 每个节以节头（如 "acknowledgments"）开始。
+ *
+ * @param data - 原始响应数据
+ * @param hasDone - 请求中是否包含 done
+ * @param sidebandAll - 是否协商了 sideband-all
+ * @returns 解析后的 fetch 响应
+ *
+ * @example
+ * ```ts
+ * const result = parseV2FetchResponse(responseData, true, false);
+ * if (result.packfile) {
+ *   // 处理 packfile
+ * }
+ * ```
+ */
+declare function parseV2FetchResponse(data: Buffer, _hasDone: boolean, sidebandAll: boolean): V2FetchResponse;
+/**
+ * 使用 v2 fetch 获取对象并写入对象存储
+ *
+ * 模拟 v1 fetchPack() 的语义，使 import-plan-builder 可无缝切换。
+ *
+ * @param store - 对象存储（用于写入 packfile 中的对象）
+ * @param v2Trans - v2 传输接口
+ * @param wants - want 对象哈希列表
+ * @param haves - have 对象哈希列表
+ * @param features - 服务端 fetch 命令特性
+ * @returns 导入的对象数量
+ */
+declare function v2FetchObjects(db: ObjectDatabase, v2Trans: V2GitServiceTransport, wants: string[], haves?: string[], features?: string[]): Promise<{
+  objectCount: number;
+}>;
+//#endregion
+export { V2FetchError, V2FetchParams, parseV2FetchResponse, v2Fetch, v2FetchObjects };

package/dist/transport/client/upload-pack/fetch.mjs

@@ -0,0 +1,392 @@
+import { GitError } from "../../../core/errors.mjs";
+import { packObjectToRaw } from "../../../pack/pack-reader-types.mjs";
+import { createPackReader } from "../../../pack/pack-reader.mjs";
+import { splitPktLinesFromBuffer } from "../../protocol/pkt-line.mjs";
+//#region src/transport/client/upload-pack/fetch.ts
+/**
+* v2 fetch 命令
+*
+* 在 Git Wire 协议 v2 中，fetch 替代了 v1 的 upload-pack 协商 + packfile 传输。
+* 支持 want/have/done、want-ref、shallow、thin-pack 等参数。
+*
+* 请求格式：
+* ```
+* command=fetch\n
+* agent=nano-git/0.1\n
+* ofs-delta\n
+* include-tag\n
+* 0001
+* want <oid>\n
+* have <oid>\n
+* done\n
+* 0000
+* ```
+*
+* 响应格式（节之间由 0001 分隔）：
+* ```
+* acknowledgments\n
+* NAK\n (或 ACK <oid>\n ... ready\n)
+* 0001
+* shallow-info\n
+* shallow <oid>\n
+* 0001
+* wanted-refs\n
+* <oid> <refname>\n
+* 0001
+* packfile\n
+* [side-band 多路复用数据]
+* 0000
+* ```
+*
+* @see https://git-scm.com/docs/protocol-v2#_fetch
+*/
+/**
+* v2 fetch 命令错误
+*/
+var V2FetchError = class extends GitError {
+	constructor(message) {
+		super(`v2 fetch error: ${message}`);
+		this.name = "V2FetchError";
+	}
+};
+/** 单轮最多发送的 have 数量 */
+const MAX_HAVES_PER_ROUND = 32;
+/** 侧信道通道编号 */
+const CHANNEL_PACKFILE = 1;
+/**
+* 执行 v2 fetch 命令
+*
+* 构建并发送 fetch 请求，返回解析后的完整响应。
+*
+* @param transport - v2 传输接口
+* @param params - fetch 参数
+* @param features - 服务端 fetch 命令支持的附加特性
+* @returns 解析后的 fetch 响应
+* @throws {V2FetchError} 当 wants 为空时
+*
+* @example
+* ```ts
+* const result = await v2Fetch(transport, {
+*   wants: [hash1, hash2],
+*   ofsDelta: true,
+*   done: true,
+* });
+* console.log(result.packfile?.length); // packfile 数据长度
+* ```
+*/
+async function v2Fetch(transport, params, features) {
+	if (params.wants.length === 0) throw new V2FetchError("No wants specified for fetch");
+	const hasFeature = (name) => features !== void 0 && features.includes(name);
+	const args = [];
+	if (params.thinPack) args.push("thin-pack");
+	if (params.noProgress) args.push("no-progress");
+	if (params.includeTag) args.push("include-tag");
+	if (params.ofsDelta) args.push("ofs-delta");
+	if (params.sidebandAll) args.push("sideband-all");
+	if (params.waitForDone) args.push("wait-for-done");
+	for (const oid of params.wants) args.push(`want ${oid}`);
+	if (params.wantRefs && hasFeature("ref-in-want")) for (const ref of params.wantRefs) args.push(`want-ref ${ref}`);
+	if (params.done) args.push("done");
+	if (!params.done && params.haves) for (const oid of params.haves) args.push(`have ${oid}`);
+	if (params.shallow && hasFeature("shallow")) for (const oid of params.shallow) args.push(`shallow ${oid}`);
+	if (params.deepen !== void 0 && hasFeature("shallow")) args.push(`deepen ${params.deepen}`);
+	if (params.deepenRelative && hasFeature("shallow")) args.push("deepen-relative");
+	if (params.deepenSince !== void 0 && hasFeature("shallow")) args.push(`deepen-since ${params.deepenSince}`);
+	if (params.deepenNot && hasFeature("shallow")) for (const rev of params.deepenNot) args.push(`deepen-not ${rev}`);
+	if (params.filter && hasFeature("filter")) args.push(`filter ${params.filter}`);
+	return parseV2FetchResponse(await transport.command("fetch", args, []), params.done ?? false, hasFeature("sideband-all"));
+}
+/**
+* 解析 v2 fetch 响应
+*
+* v2 fetch 响应由多个节组成，节之间由 delimiter (0001) 分隔。
+* 每个节以节头（如 "acknowledgments"）开始。
+*
+* @param data - 原始响应数据
+* @param hasDone - 请求中是否包含 done
+* @param sidebandAll - 是否协商了 sideband-all
+* @returns 解析后的 fetch 响应
+*
+* @example
+* ```ts
+* const result = parseV2FetchResponse(responseData, true, false);
+* if (result.packfile) {
+*   // 处理 packfile
+* }
+* ```
+*/
+function parseV2FetchResponse(data, _hasDone, sidebandAll) {
+	const { lines: pktLines, trailing } = splitPktLinesFromBuffer(data);
+	if (sidebandAll && pktLines.length > 0) {
+		const first = pktLines[0];
+		if (first?.type === "data" && first.payload.length > 1) {
+			const withoutChannel = Buffer.concat(pktLines.filter((p) => p.type === "data").map((p) => p.payload.subarray(1)));
+			return parseV2FetchResponse(Buffer.concat([withoutChannel, trailing]), false, false);
+		}
+	}
+	const sections = [];
+	let currentSection = null;
+	const packfileFrames = [];
+	let inPackfile = false;
+	for (const pkt of pktLines) {
+		if (pkt.type === "flush") break;
+		if (pkt.type === "delimiter") {
+			currentSection = null;
+			inPackfile = false;
+			continue;
+		}
+		if (pkt.type !== "data") continue;
+		const payload = pkt.payload;
+		const text = payload.toString("utf-8");
+		const trimmed = text.replace(/\n$/, "");
+		if (currentSection === null && !inPackfile) {
+			currentSection = {
+				header: trimmed,
+				lines: []
+			};
+			sections.push(currentSection);
+			if (trimmed === "packfile") {
+				inPackfile = true;
+				const headerEndIndex = text.indexOf("\n") + 1;
+				if (headerEndIndex > 0 && headerEndIndex < payload.length) packfileFrames.push(payload.subarray(headerEndIndex));
+			}
+		} else if (inPackfile) packfileFrames.push(payload);
+		else if (currentSection) currentSection.lines.push(payload);
+	}
+	if (trailing.length > 0) packfileFrames.push(trailing);
+	const result = {};
+	for (const section of sections) switch (section.header) {
+		case "acknowledgments":
+			result.acknowledgments = parseAcknowledgments(section.lines);
+			break;
+		case "shallow-info":
+			result.shallowInfo = parseShallowInfo(section.lines);
+			break;
+		case "wanted-refs":
+			result.wantedRefs = parseWantedRefs(section.lines);
+			break;
+		case "packfile-uris":
+			result.packfileUris = parsePackfileUris(section.lines);
+			break;
+		case "packfile":
+			if (packfileFrames.length > 0) result.packfile = extractPackfileFromFrames(packfileFrames);
+			break;
+	}
+	return result;
+}
+/**
+* 解析 acknowledgments 节
+*
+* ```
+* acknowledgments\n
+* NAK\n
+* --- 或 ---
+* ACK <oid>\n
+* ACK <oid>\n
+* ready\n
+* ```
+*/
+function parseAcknowledgments(lines) {
+	const acks = [];
+	let nak = false;
+	let ready = false;
+	for (const line of lines) {
+		const text = line.toString("utf-8").trim();
+		if (text === "NAK") nak = true;
+		else if (text === "ready") ready = true;
+		else if (text.startsWith("ACK ")) acks.push(text.substring(4).trim());
+	}
+	return {
+		nak,
+		acks,
+		ready
+	};
+}
+/**
+* 解析 shallow-info 节
+*
+* ```
+* shallow-info\n
+* shallow <oid>\n
+* unshallow <oid>\n
+* ```
+*/
+function parseShallowInfo(lines) {
+	const shallow = [];
+	const unshallow = [];
+	for (const line of lines) {
+		const text = line.toString("utf-8").trim();
+		if (text.startsWith("shallow ")) shallow.push(text.substring(8).trim());
+		else if (text.startsWith("unshallow ")) unshallow.push(text.substring(10).trim());
+	}
+	return {
+		shallow,
+		unshallow
+	};
+}
+/**
+* 解析 wanted-refs 节
+*
+* ```
+* wanted-refs\n
+* <oid> <refname>\n
+* ```
+*/
+function parseWantedRefs(lines) {
+	const refs = [];
+	for (const line of lines) {
+		const text = line.toString("utf-8").trim();
+		if (text.length === 0) continue;
+		const spaceIdx = text.indexOf(" ");
+		if (spaceIdx === -1) continue;
+		refs.push({
+			oid: text.substring(0, spaceIdx),
+			refname: text.substring(spaceIdx + 1).trim()
+		});
+	}
+	return refs;
+}
+/**
+* 解析 packfile-uris 节
+*
+* ```
+* packfile-uris\n
+* <oid> <uri>\n
+* ```
+*/
+function parsePackfileUris(lines) {
+	const uris = [];
+	for (const line of lines) {
+		const text = line.toString("utf-8").trim();
+		if (text.length === 0) continue;
+		const spaceIdx = text.indexOf(" ");
+		if (spaceIdx === -1) continue;
+		uris.push({
+			oid: text.substring(0, spaceIdx),
+			uri: text.substring(spaceIdx + 1).trim()
+		});
+	}
+	return uris;
+}
+/**
+* 从 side-band pkt-line payload 帧中提取 packfile 数据
+*
+* v2 fetch 响应中 packfile 节的每个 pkt-line payload 格式为：
+* <1-byte-channel><data>
+* channel 1 = packfile 数据
+* channel 2 = 进度消息
+* channel 3 = 致命错误
+*
+* @param frames - pkt-line payload 数组（不含长度前缀，含 channel 字节）
+* @returns 拼接后的完整 packfile buffer
+*/
+function extractPackfileFromFrames(frames) {
+	const chunks = [];
+	for (const frame of frames) {
+		if (frame.length < 1) continue;
+		if (frame[0] === CHANNEL_PACKFILE) chunks.push(frame.subarray(1));
+	}
+	if (chunks.length === 0) throw new V2FetchError("No packfile data found in fetch response");
+	return Buffer.concat(chunks);
+}
+/**
+* 执行 v2 多轮 fetch 协商
+*
+* v2 的 fetch 协商与 v1 类似，但使用不同的请求/响应格式。
+* 多轮协商中，中间轮以 flush 结尾（不含 done），
+* 最终轮以 done 结尾。
+*
+* @param transport - v2 传输接口
+* @param wants - want 列表
+* @param haveCandidates - have 候选列表（按时间从旧到新排序）
+* @param features - 服务端 fetch 命令特性
+* @returns fetch 响应（含 packfile）
+*/
+async function negotiateV2Fetch(transport, wants, haveCandidates, features) {
+	if (wants.length === 0) throw new V2FetchError("No wants specified for fetch");
+	if (haveCandidates.length === 0) return v2Fetch(transport, {
+		wants,
+		ofsDelta: true,
+		done: true
+	}, features);
+	const state = {
+		sent: /* @__PURE__ */ new Set(),
+		candidates: haveCandidates,
+		offset: 0,
+		common: []
+	};
+	const MAX_ROUNDS = 10;
+	for (let round = 0; round < MAX_ROUNDS; round++) {
+		const roundHaves = [];
+		for (const c of state.common) if (!state.sent.has(c)) {
+			roundHaves.push(c);
+			state.sent.add(c);
+		}
+		let remaining = MAX_HAVES_PER_ROUND - roundHaves.length;
+		while (remaining > 0 && state.offset < state.candidates.length) {
+			const candidate = state.candidates[state.offset];
+			state.offset++;
+			if (!state.sent.has(candidate)) {
+				roundHaves.push(candidate);
+				state.sent.add(candidate);
+				remaining--;
+			}
+		}
+		const isFinalRound = roundHaves.length === 0 || round === MAX_ROUNDS - 1;
+		const response = await v2Fetch(transport, {
+			wants,
+			haves: roundHaves,
+			ofsDelta: true
+		}, features);
+		const ack = response.acknowledgments;
+		if (!ack) {
+			if (response.packfile) return response;
+			continue;
+		}
+		if (ack.acks.length > 0) {
+			for (const ackOid of ack.acks) if (!state.common.includes(ackOid)) state.common.push(ackOid);
+		}
+		if (ack.ready) return v2Fetch(transport, {
+			wants,
+			haves: roundHaves,
+			ofsDelta: true,
+			done: true
+		}, features);
+		if (isFinalRound) return v2Fetch(transport, {
+			wants,
+			haves: roundHaves,
+			ofsDelta: true,
+			done: true
+		}, features);
+	}
+	return v2Fetch(transport, {
+		wants,
+		ofsDelta: true,
+		done: true
+	}, features);
+}
+/**
+* 使用 v2 fetch 获取对象并写入对象存储
+*
+* 模拟 v1 fetchPack() 的语义，使 import-plan-builder 可无缝切换。
+*
+* @param store - 对象存储（用于写入 packfile 中的对象）
+* @param v2Trans - v2 传输接口
+* @param wants - want 对象哈希列表
+* @param haves - have 对象哈希列表
+* @param features - 服务端 fetch 命令特性
+* @returns 导入的对象数量
+*/
+async function v2FetchObjects(db, v2Trans, wants, haves, features) {
+	const result = await negotiateV2Fetch(v2Trans, wants, haves ?? [], features);
+	if (!result.packfile || result.packfile.length === 0) return { objectCount: 0 };
+	const reader = createPackReader(result.packfile);
+	let count = 0;
+	for (const packObj of reader.objects()) {
+		db.ingest(packObjectToRaw(packObj));
+		count++;
+	}
+	return { objectCount: count };
+}
+//#endregion
+export { V2FetchError, parseV2FetchResponse, v2Fetch, v2FetchObjects };

package/dist/transport/client/upload-pack/http.d.mts

@@ -0,0 +1,29 @@
+import { V2GitServiceTransport } from "./types.mjs";
+
+//#region src/transport/client/upload-pack/http.d.ts
+/**
+ * v2 HTTP 传输错误
+ */
+declare class V2SmartHttpError extends Error {
+  constructor(message: string);
+}
+/**
+ * 创建 v2 HTTP 传输适配器
+ *
+ * @param url - 远端仓库 URL
+ * @param options - 可选认证选项
+ * @returns v2 传输接口
+ *
+ * @example
+ * ```ts
+ * const transport = createV2HttpTransport("https://github.com/user/repo");
+ * const caps = await transport.advertise();
+ * const refs = await transport.command("ls-refs", ["symrefs", "peel"]);
+ * ```
+ */
+declare function createV2HttpTransport(url: string, options?: {
+  token?: string;
+  headers?: Record<string, string>;
+}): V2GitServiceTransport;
+//#endregion
+export { V2SmartHttpError, createV2HttpTransport };

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

@@ -0,0 +1,79 @@
+import { encodeDelimiterPkt, encodeFlushPkt, encodePktLine } from "../../protocol/pkt-line.mjs";
+import { parseV2CapabilityAdvertisement } from "./capability-advertisement.mjs";
+//#region src/transport/client/upload-pack/http.ts
+/**
+* v2 HTTP 传输适配器
+*
+* Git Wire 协议 v2 的 HTTP 传输层。
+* 负责构建 v2 命令式请求并发送到远端。
+*
+* v2 HTTP 传输流程：
+* 1. advertise() — 获取能力广告（含版本声明）
+* 2. command()  — 执行单个命令（ls-refs / fetch / push / object-info）
+*
+* @see https://git-scm.com/docs/protocol-v2#_initial_client_request
+*/
+/**
+* v2 HTTP 传输错误
+*/
+var V2SmartHttpError = class extends Error {
+	constructor(message) {
+		super(`v2 smart-http error: ${message}`);
+		this.name = "V2SmartHttpError";
+	}
+};
+/** v2 advertise 路径（与 v1 相同，但增加 Git-Protocol 头） */
+const ADVERTISE_PATH = "/info/refs";
+/** v2 命令执行路径 */
+const COMMAND_PATH = "/git-upload-pack";
+/**
+* 创建 v2 HTTP 传输适配器
+*
+* @param url - 远端仓库 URL
+* @param options - 可选认证选项
+* @returns v2 传输接口
+*
+* @example
+* ```ts
+* const transport = createV2HttpTransport("https://github.com/user/repo");
+* const caps = await transport.advertise();
+* const refs = await transport.command("ls-refs", ["symrefs", "peel"]);
+* ```
+*/
+function createV2HttpTransport(url, options) {
+	const baseUrl = url.replace(/\/$/, "");
+	const baseHeaders = {
+		"User-Agent": "nano-git/0.1",
+		"Content-Type": "application/x-git-upload-pack-request",
+		Accept: "application/x-git-upload-pack-result",
+		"Git-Protocol": "version=2",
+		...options?.headers
+	};
+	if (options?.token) baseHeaders.Authorization = `Bearer ${options.token}`;
+	return {
+		async advertise() {
+			const response = await fetch(`${baseUrl}${ADVERTISE_PATH}?service=git-upload-pack`, { headers: baseHeaders });
+			if (!response.ok) throw new V2SmartHttpError(`advertise failed: ${response.status} ${response.statusText}`);
+			return parseV2CapabilityAdvertisement(Buffer.from(await response.arrayBuffer()));
+		},
+		async command(command, args, capabilities, body) {
+			const lines = [];
+			lines.push(encodePktLine(`command=${command}\n`));
+			if (capabilities) for (const cap of capabilities) lines.push(encodePktLine(`${cap}\n`));
+			lines.push(encodeDelimiterPkt());
+			if (args) for (const arg of args) lines.push(encodePktLine(`${arg}\n`));
+			lines.push(encodeFlushPkt());
+			if (body) lines.push(body);
+			const requestBody = Buffer.concat(lines);
+			const response = await fetch(`${baseUrl}${COMMAND_PATH}`, {
+				method: "POST",
+				headers: baseHeaders,
+				body: requestBody
+			});
+			if (!response.ok) throw new V2SmartHttpError(`command "${command}" failed: ${response.status} ${response.statusText}`);
+			return Buffer.from(await response.arrayBuffer());
+		}
+	};
+}
+//#endregion
+export { V2SmartHttpError, createV2HttpTransport };

package/dist/transport/client/upload-pack/ls-refs.d.mts

@@ -0,0 +1,75 @@
+import { GitError } from "../../../core/errors.mjs";
+import { RefAdvertisement } from "../../protocol/types.mjs";
+import { LsRefsEntry, V2GitServiceTransport } from "./types.mjs";
+
+//#region src/transport/client/upload-pack/ls-refs.d.ts
+/**
+ * ls-refs 命令错误
+ */
+declare class LsRefsError extends GitError {
+  constructor(message: string);
+}
+/**
+ * ls-refs 请求参数
+ */
+interface LsRefsOptions {
+  /** 请求符号引用信息 */
+  readonly symrefs?: boolean;
+  /** 请求 peeled tag 信息 */
+  readonly peel?: boolean;
+  /** 按前缀过滤 refs，如 ["refs/heads/", "refs/tags/"] */
+  readonly refPrefixes?: string[];
+  /** 请求 unborn HEAD 信息 */
+  readonly unborn?: boolean;
+}
+/**
+ * 执行 ls-refs 命令
+ *
+ * @param transport - v2 传输接口
+ * @param options - ls-refs 请求选项
+ * @returns 解析后的 ref 条目列表
+ *
+ * @example
+ * ```ts
+ * const entries = await lsRefs(transport, {
+ *   symrefs: true,
+ *   peel: true,
+ *   refPrefixes: ["refs/heads/"],
+ * });
+ * ```
+ */
+declare function lsRefs(transport: V2GitServiceTransport, options?: LsRefsOptions): Promise<LsRefsEntry[]>;
+/**
+ * 解析 ls-refs 响应
+ *
+ * 从原始 Buffer 中解析 ls-refs 条目。
+ *
+ * @param data - ls-refs 命令的原始响应数据
+ * @returns 解析后的 ref 条目列表
+ *
+ * @example
+ * ```ts
+ * const entries = parseLsRefsResponse(response);
+ * console.log(entries[0].refname); // "refs/heads/main"
+ * ```
+ */
+declare function parseLsRefsResponse(data: Buffer): LsRefsEntry[];
+/**
+ * 将 v2 ls-refs 结果转换为 v1 兼容的 RefAdvertisement
+ *
+ * 用于 ImportSession 的透明升级：v2 获取 refs 后，
+ * 包装为 v1 的 RefAdvertisement 格式，使上游代码无需改动。
+ *
+ * @param entries - ls-refs 返回的 ref 条目
+ * @returns v1 兼容的 RefAdvertisement
+ *
+ * @example
+ * ```ts
+ * const entries = await lsRefs(transport);
+ * const adv = lsRefsToRefAdvertisement(entries);
+ * // 可传递给 ImportSession
+ * ```
+ */
+declare function lsRefsToRefAdvertisement(entries: LsRefsEntry[]): RefAdvertisement;
+//#endregion
+export { LsRefsError, LsRefsOptions, lsRefs, lsRefsToRefAdvertisement, parseLsRefsResponse };