nano-git 0.1.0 → 0.2.1

package/dist/log/walk.mjs

@@ -0,0 +1,274 @@
+import { tryReadObject } from "../objects/raw.mjs";
+//#region src/log/walk.ts
+/**
+* 提交日志遍历核心实现
+*
+* 提供 Generator 风格的 `walkLogEntries`，支持按提交时间降序
+* 或严格拓扑序遍历提交历史。
+*
+* @example
+* ```ts
+* // 从 HEAD 开始遍历最近 10 条提交
+* const headHash = resolveRefHash(repo.refs, "HEAD")!;
+* for (const entry of walkLogEntries(repo.objects, { from: [headHash], maxCount: 10 })) {
+*   console.log(entry.hash, entry.commit.message);
+* }
+*
+* // 等价于 git log main..feature
+* const featureHash = resolveRefHash(repo.refs, "refs/heads/feature")!;
+* const mainHash = resolveRefHash(repo.refs, "refs/heads/main")!;
+* for (const entry of walkLogEntries(repo.objects, { from: [featureHash], exclude: [mainHash] })) {
+*   console.log(entry.hash, entry.commit.message);
+* }
+* ```
+*/
+var MaxHeapByTimestamp = class {
+	heap = [];
+	get size() {
+		return this.heap.length;
+	}
+	push(entry) {
+		this.heap.push(entry);
+		this.siftUp(this.heap.length - 1);
+	}
+	pop() {
+		if (this.heap.length === 0) return void 0;
+		const top = this.heap[0];
+		const bottom = this.heap.pop();
+		if (this.heap.length > 0) {
+			this.heap[0] = bottom;
+			this.siftDown(0);
+		}
+		return top;
+	}
+	siftUp(idx) {
+		const heap = this.heap;
+		while (idx > 0) {
+			const parent = idx - 1 >> 1;
+			if (heap[parent].commit.committer.timestamp >= heap[idx].commit.committer.timestamp) break;
+			[heap[parent], heap[idx]] = [heap[idx], heap[parent]];
+			idx = parent;
+		}
+	}
+	siftDown(idx) {
+		const heap = this.heap;
+		const end = heap.length;
+		while (true) {
+			let largest = idx;
+			const left = (idx << 1) + 1;
+			const right = left + 1;
+			if (left < end && heap[left].commit.committer.timestamp > heap[largest].commit.committer.timestamp) largest = left;
+			if (right < end && heap[right].commit.committer.timestamp > heap[largest].commit.committer.timestamp) largest = right;
+			if (largest === idx) break;
+			[heap[idx], heap[largest]] = [heap[largest], heap[idx]];
+			idx = largest;
+		}
+	}
+};
+/**
+* 递归标记排除提交及其所有祖先
+*/
+function markExcluded(source, hash, excluded) {
+	const stack = [hash];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (excluded.has(current)) continue;
+		excluded.add(current);
+		const obj = tryReadObject(source, current);
+		if (obj?.type === "commit") {
+			for (const parent of obj.parents) if (!excluded.has(parent)) stack.push(parent);
+		}
+	}
+}
+/**
+* 按提交时间降序遍历提交历史
+*
+* 使用最大堆按时间戳排序，每次弹出最新提交后将其 parent 入堆。
+* 可配合 firstParent、since、until、skip、maxCount 等过滤条件。
+*/
+function* walkByDate(source, from, excluded, firstParent, skip, maxCount, since, until) {
+	const queue = new MaxHeapByTimestamp();
+	const seen = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	for (const hash of from) {
+		if (excluded.has(hash) || seen.has(hash)) continue;
+		const obj = tryReadObject(source, hash);
+		if (obj?.type !== "commit") continue;
+		seen.add(hash);
+		queue.push({
+			hash,
+			commit: obj
+		});
+	}
+	let skipped = 0;
+	let emitted = 0;
+	while (queue.size > 0) {
+		if (maxCount !== void 0 && emitted >= maxCount) break;
+		const entry = queue.pop();
+		if (visited.has(entry.hash)) continue;
+		if (excluded.has(entry.hash)) continue;
+		if (since !== void 0 && entry.commit.committer.timestamp < since) continue;
+		if (until !== void 0 && entry.commit.committer.timestamp > until) {
+			enqueueParents(source, entry.commit.parents, firstParent, excluded, seen, visited, queue);
+			continue;
+		}
+		if (skipped < skip) {
+			skipped++;
+			visited.add(entry.hash);
+			enqueueParents(source, entry.commit.parents, firstParent, excluded, seen, visited, queue);
+			continue;
+		}
+		visited.add(entry.hash);
+		emitted++;
+		yield {
+			hash: entry.hash,
+			commit: entry.commit
+		};
+		enqueueParents(source, entry.commit.parents, firstParent, excluded, seen, visited, queue);
+	}
+}
+/**
+* 将提交的 parent 批量入堆
+*/
+function enqueueParents(source, parents, firstParent, excluded, seen, visited, queue) {
+	const targetParents = firstParent && parents.length > 0 ? [parents[0]] : parents;
+	for (const parentHash of targetParents) {
+		if (seen.has(parentHash) || excluded.has(parentHash)) continue;
+		seen.add(parentHash);
+		const obj = tryReadObject(source, parentHash);
+		if (obj?.type !== "commit") continue;
+		queue.push({
+			hash: parentHash,
+			commit: obj
+		});
+	}
+}
+/**
+* 生成严格拓扑序（子提交先于父提交）的提交迭代器
+*
+* 实现 Kahn 算法：
+* 1. 收集所有起点可达的提交，构建 parent→children 映射
+* 2. 统计每个提交的未输出子提交数（childCount）
+* 3. 将 childCount === 0 的提交入堆（同层按时间戳降序）
+* 4. 每次弹出堆顶输出，递减其 parent 的 childCount
+* 5. parent 的 childCount 归零时入堆
+*/
+function* walkTopo(source, from, excluded, firstParent, skip, maxCount, since, until) {
+	const commits = /* @__PURE__ */ new Map();
+	const children = /* @__PURE__ */ new Map();
+	const stack = [...from];
+	while (stack.length > 0) {
+		const hash = stack.pop();
+		if (commits.has(hash) || excluded.has(hash)) continue;
+		const obj = tryReadObject(source, hash);
+		if (obj?.type !== "commit") continue;
+		commits.set(hash, obj);
+		if (!children.has(hash)) children.set(hash, []);
+		const targetParents = firstParent && obj.parents.length > 0 ? [obj.parents[0]] : obj.parents;
+		for (const parentHash of targetParents) {
+			if (commits.has(parentHash) || excluded.has(parentHash)) continue;
+			if (!children.has(parentHash)) children.set(parentHash, []);
+			children.get(parentHash).push(hash);
+			stack.push(parentHash);
+		}
+	}
+	if (commits.size === 0) return;
+	const childCount = /* @__PURE__ */ new Map();
+	const pq = new MaxHeapByTimestamp();
+	for (const hash of commits.keys()) {
+		const count = children.get(hash)?.length ?? 0;
+		childCount.set(hash, count);
+		if (count === 0) pq.push({
+			hash,
+			commit: commits.get(hash)
+		});
+	}
+	let skipped = 0;
+	let emitted = 0;
+	while (pq.size > 0) {
+		if (maxCount !== void 0 && emitted >= maxCount) break;
+		const entry = pq.pop();
+		if (since !== void 0 && entry.commit.committer.timestamp < since) {
+			decrementParentCounts(entry.commit.parents, firstParent, childCount, commits, pq);
+			continue;
+		}
+		if (until !== void 0 && entry.commit.committer.timestamp > until) {
+			decrementParentCounts(entry.commit.parents, firstParent, childCount, commits, pq);
+			continue;
+		}
+		if (skipped < skip) {
+			skipped++;
+			decrementParentCounts(entry.commit.parents, firstParent, childCount, commits, pq);
+			continue;
+		}
+		emitted++;
+		yield {
+			hash: entry.hash,
+			commit: entry.commit
+		};
+		decrementParentCounts(entry.commit.parents, firstParent, childCount, commits, pq);
+	}
+}
+/**
+* 递减 parent 的 childCount，归零时入堆
+*/
+function decrementParentCounts(parents, firstParent, childCount, commits, pq) {
+	const targetParents = firstParent && parents.length > 0 ? [parents[0]] : parents;
+	for (const parentHash of targetParents) {
+		const count = childCount.get(parentHash);
+		if (count === void 0) continue;
+		const newCount = count - 1;
+		childCount.set(parentHash, newCount);
+		if (newCount === 0) {
+			const parentCommit = commits.get(parentHash);
+			if (parentCommit) pq.push({
+				hash: parentHash,
+				commit: parentCommit
+			});
+		}
+	}
+}
+/**
+* 遍历提交历史日志
+*
+* 从指定的起点哈希出发，沿 parent 链回溯，按指定排序策略输出提交。
+* 不涉及 ref 解析——调用方需自行将 ref 名称解析为 SHA1。
+*
+* @param source - 对象源（通常是 `Repository.objects`）
+* @param options - 遍历选项
+* @returns 按序输出的提交日志条目生成器
+*
+* @example
+* ```ts
+* const headHash = resolveRefHash(repo.refs, "HEAD")!;
+* for (const entry of walkLogEntries(repo.objects, { from: [headHash], maxCount: 5 })) {
+*   console.log(entry.hash, entry.commit.subject);
+* }
+* ```
+*
+* @example
+* ```ts
+* // 等价于 git log --oneline --since=1600000000 --until=1700000000
+* for (const entry of walkLogEntries(repo.objects, {
+*   from: [headHash],
+*   since: 1600000000,
+*   until: 1700000000,
+* })) {
+*   console.log(entry.hash.slice(0, 7), entry.commit.message.split("\n")[0]);
+* }
+* ```
+*/
+function walkLogEntries(source, options = {}) {
+	const { from = [], exclude = [], skip: skipCount = 0, order = "date", since, until, firstParent = false, maxCount } = options;
+	if (from.length === 0) return emptyGenerator();
+	const excluded = /* @__PURE__ */ new Set();
+	for (const hash of exclude) markExcluded(source, hash, excluded);
+	if (order === "topo") return walkTopo(source, from, excluded, firstParent, skipCount, maxCount, since, until);
+	return walkByDate(source, from, excluded, firstParent, skipCount, maxCount, since, until);
+}
+/** 返回一个空的 Generator（不产生任何值，直接 done） */
+function emptyGenerator() {
+	return [][Symbol.iterator]();
+}
+//#endregion
+export { walkLogEntries };

package/dist/odb/sqlite.d.mts

@@ -0,0 +1,23 @@
+import { ObjectDatabase } from "../core/types/odb.mjs";
+import { Database } from "bun:sqlite";
+
+//#region src/odb/sqlite.d.ts
+/**
+ * 创建基于 SQLite 的对象数据库
+ *
+ * @param db - 已打开的 bun:sqlite Database 实例
+ * @returns 符合 ObjectDatabase 接口的存储后端
+ *
+ * @example
+ * ```ts
+ * import { Database } from "bun:sqlite";
+ * const db = new Database("/tmp/repo.sqlite");
+ * const store = createSqliteObjectStore(db);
+ *
+ * store.ingest(raw);
+ * const obj = store.read(hash);
+ * ```
+ */
+declare function createSqliteObjectStore(db: Database): ObjectDatabase;
+//#endregion
+export { createSqliteObjectStore };

package/dist/odb/sqlite.mjs

@@ -0,0 +1,83 @@
+import { ObjectNotFoundError } from "../core/errors.mjs";
+import { sha1 } from "../core/types.mjs";
+import { hashObject } from "../core/hash-digest.mjs";
+//#region src/odb/sqlite.ts
+/**
+* 基于 SQLite 的对象数据库（raw-first）
+*
+* 所有对象存储在 SQLite 数据库的 objects 表中。
+* 使用 INSERT OR IGNORE 实现幂等写入，使用 db.transaction() 实现批量原子写入。
+*
+* 表创建由上层 createSqliteRepositoryBackend 负责，
+* 本模块只操作已存在的表，不负责 DDL。
+*/
+/**
+* 创建基于 SQLite 的对象数据库
+*
+* @param db - 已打开的 bun:sqlite Database 实例
+* @returns 符合 ObjectDatabase 接口的存储后端
+*
+* @example
+* ```ts
+* import { Database } from "bun:sqlite";
+* const db = new Database("/tmp/repo.sqlite");
+* const store = createSqliteObjectStore(db);
+*
+* store.ingest(raw);
+* const obj = store.read(hash);
+* ```
+*/
+function createSqliteObjectStore(db) {
+	const selectStmt = db.query("SELECT hash, type, content FROM objects WHERE hash = ?");
+	const existsStmt = db.query("SELECT 1 FROM objects WHERE hash = ?");
+	const insertStmt = db.query("INSERT OR IGNORE INTO objects (hash, type, content) VALUES (?, ?, ?)");
+	const deleteStmt = db.query("DELETE FROM objects WHERE hash = ?");
+	const listStmt = db.query("SELECT hash FROM objects ORDER BY hash");
+	/** 批量插入的事务包装 */
+	const ingestManyTx = db.transaction((objects) => {
+		for (const raw of objects) {
+			const expectedHash = hashObject(raw.type, raw.content);
+			if (expectedHash !== raw.hash) throw new Error(`RawGitObject hash mismatch: expected ${expectedHash}, got ${raw.hash}`);
+			insertStmt.run(raw.hash, raw.type, raw.content);
+		}
+	});
+	return {
+		ingest(raw) {
+			const expectedHash = hashObject(raw.type, raw.content);
+			if (expectedHash !== raw.hash) throw new Error(`RawGitObject hash mismatch: expected ${expectedHash}, got ${raw.hash}`);
+			insertStmt.run(raw.hash, raw.type, raw.content);
+		},
+		ingestMany(objects) {
+			ingestManyTx(objects);
+		},
+		read(hash) {
+			const row = selectStmt.get(hash);
+			if (!row) throw new ObjectNotFoundError(hash);
+			return {
+				hash: sha1(row.hash),
+				type: row.type,
+				content: Buffer.from(row.content)
+			};
+		},
+		tryRead(hash) {
+			const row = selectStmt.get(hash);
+			if (!row) return;
+			return {
+				hash: sha1(row.hash),
+				type: row.type,
+				content: Buffer.from(row.content)
+			};
+		},
+		exists(hash) {
+			return existsStmt.get(hash) !== null;
+		},
+		list() {
+			return listStmt.all().map((row) => sha1(row.hash));
+		},
+		delete(hash) {
+			deleteStmt.run(hash);
+		}
+	};
+}
+//#endregion
+export { createSqliteObjectStore };

package/dist/refs/shallow/sqlite.d.mts

@@ -0,0 +1,23 @@
+import { ShallowStore } from "../../core/types/shallow.mjs";
+import { Database } from "bun:sqlite";
+
+//#region src/refs/shallow/sqlite.d.ts
+/**
+ * 创建基于 SQLite 的 shallow 边界存储
+ *
+ * @param db - 已打开的 bun:sqlite Database 实例
+ * @returns 符合 ShallowStore 接口的存储后端
+ *
+ * @example
+ * ```ts
+ * import { Database } from "bun:sqlite";
+ * const db = new Database("/tmp/repo.sqlite");
+ * const store = createSqliteShallowStore(db);
+ *
+ * store.write([hashA, hashB]);
+ * console.log(store.isShallow(hashA)); // true
+ * ```
+ */
+declare function createSqliteShallowStore(db: Database): ShallowStore;
+//#endregion
+export { createSqliteShallowStore };

package/dist/refs/shallow/sqlite.mjs

@@ -0,0 +1,61 @@
+import { sha1 } from "../../core/types.mjs";
+//#region src/refs/shallow/sqlite.ts
+/**
+* 基于 SQLite 的 Shallow 存储
+*
+* 所有 shallow 边界存储在 SQLite 数据库的 shallow 表中。
+* write 使用 DELETE + INSERT 全量替换模式（与 memory/file 后端一致）。
+* applyUpdate 使用 SQL 事务做增量更新。
+*
+* 表创建由上层 createSqliteRepositoryBackend 负责，
+* 本模块只操作已存在的表，不负责 DDL。
+*/
+/**
+* 创建基于 SQLite 的 shallow 边界存储
+*
+* @param db - 已打开的 bun:sqlite Database 实例
+* @returns 符合 ShallowStore 接口的存储后端
+*
+* @example
+* ```ts
+* import { Database } from "bun:sqlite";
+* const db = new Database("/tmp/repo.sqlite");
+* const store = createSqliteShallowStore(db);
+*
+* store.write([hashA, hashB]);
+* console.log(store.isShallow(hashA)); // true
+* ```
+*/
+function createSqliteShallowStore(db) {
+	const selectAllStmt = db.query("SELECT hash FROM shallow ORDER BY hash");
+	const selectExistsStmt = db.query("SELECT 1 FROM shallow WHERE hash = ?");
+	const deleteAllStmt = db.query("DELETE FROM shallow");
+	const insertStmt = db.query("INSERT OR IGNORE INTO shallow (hash) VALUES (?)");
+	const deleteOneStmt = db.query("DELETE FROM shallow WHERE hash = ?");
+	/** 全量替换事务 */
+	const replaceAllTx = db.transaction((boundaries) => {
+		deleteAllStmt.run();
+		for (const hash of boundaries) insertStmt.run(hash);
+	});
+	/** 增量更新事务 */
+	const applyUpdateTx = db.transaction((update) => {
+		for (const hash of update.unshallow) deleteOneStmt.run(hash);
+		for (const hash of update.shallow) insertStmt.run(hash);
+	});
+	return {
+		read() {
+			return selectAllStmt.all().map((row) => sha1(row.hash));
+		},
+		write(boundaries) {
+			replaceAllTx(boundaries);
+		},
+		applyUpdate(update) {
+			applyUpdateTx(update);
+		},
+		isShallow(hash) {
+			return selectExistsStmt.get(hash) !== null;
+		}
+	};
+}
+//#endregion
+export { createSqliteShallowStore };

package/dist/refs/sqlite.d.mts

@@ -0,0 +1,23 @@
+import { RefStore } from "../core/types/refs.mjs";
+import { Database } from "bun:sqlite";
+
+//#region src/refs/sqlite.d.ts
+/**
+ * 创建基于 SQLite 的 RefStore
+ *
+ * @param db - 已打开的 bun:sqlite Database 实例（生命周期由调用方管理）
+ * @returns 符合 RefStore 接口的存储后端（含事务支持）
+ *
+ * @example
+ * ```ts
+ * import { Database } from "bun:sqlite";
+ * const db = new Database("/tmp/repo.sqlite");
+ * const store = createSqliteRefStore(db);
+ *
+ * store.write("refs/heads/main", "abc123");
+ * const content = store.read("refs/heads/main");
+ * ```
+ */
+declare function createSqliteRefStore(db: Database): RefStore;
+//#endregion
+export { createSqliteRefStore };

package/dist/refs/sqlite.mjs

@@ -0,0 +1,135 @@
+import { RefNotFoundError, TransactionError } from "../core/errors.mjs";
+import { validateRefName, validateRefPrefix } from "./names.mjs";
+//#region src/refs/sqlite.ts
+/**
+* 基于 SQLite 的 Refs 存储
+*
+* 所有引用存储在 SQLite 数据库的 refs 表中。
+* 使用 INSERT OR REPLACE 实现幂等写入，使用 db.transaction() 实现事务原子性。
+*
+* 表创建由上层 createSqliteRepositoryBackend 负责，
+* 本模块只操作已存在的表，不负责 DDL。
+*/
+/**
+* 创建基于 SQLite 的 RefStore
+*
+* @param db - 已打开的 bun:sqlite Database 实例（生命周期由调用方管理）
+* @returns 符合 RefStore 接口的存储后端（含事务支持）
+*
+* @example
+* ```ts
+* import { Database } from "bun:sqlite";
+* const db = new Database("/tmp/repo.sqlite");
+* const store = createSqliteRefStore(db);
+*
+* store.write("refs/heads/main", "abc123");
+* const content = store.read("refs/heads/main");
+* ```
+*/
+function createSqliteRefStore(db) {
+	const selectStmt = db.query("SELECT target FROM refs WHERE name = ?");
+	const selectExistsStmt = db.query("SELECT 1 FROM refs WHERE name = ?");
+	const insertStmt = db.query("INSERT OR REPLACE INTO refs (name, target) VALUES (?, ?)");
+	const deleteStmt = db.query("DELETE FROM refs WHERE name = ?");
+	const listPrefixStmt = db.query("SELECT name FROM refs WHERE name >= ? AND name < ? ORDER BY name");
+	const listAllStmt = db.query("SELECT name FROM refs WHERE name LIKE 'refs/%' ORDER BY name");
+	/**
+	* 开启一个新的事务
+	*
+	* 所有变更暂存于 JS Map，commit() 时通过 SQLite 事务原子性写入。
+	*/
+	function beginTransaction(hooks) {
+		const pending = /* @__PURE__ */ new Map();
+		const snapshot = /* @__PURE__ */ new Map();
+		for (const row of listAllStmt.all()) {
+			const val = selectStmt.get(row.name);
+			if (val !== null) snapshot.set(row.name, val.target);
+		}
+		let committed = false;
+		return {
+			get pendingCount() {
+				return pending.size;
+			},
+			write(ref, content) {
+				if (committed) throw new TransactionError("Transaction already committed");
+				validateRefName(ref);
+				pending.set(ref, content.trimEnd());
+			},
+			delete(ref) {
+				if (committed) throw new TransactionError("Transaction already committed");
+				validateRefName(ref);
+				const inDb = selectExistsStmt.get(ref) !== null;
+				const inPending = pending.has(ref);
+				if (!inDb && !inPending) throw new RefNotFoundError(ref);
+				pending.set(ref, null);
+			},
+			commit() {
+				if (committed) throw new TransactionError("Transaction already committed");
+				committed = true;
+				const txSnapshot = freezePending(pending);
+				try {
+					for (const hook of hooks ?? []) hook.onPrepare?.(txSnapshot);
+					db.transaction(() => {
+						for (const [ref, content] of pending) if (content === null) {
+							if (!snapshot.has(ref) && !selectExistsStmt.get(ref)) throw new RefNotFoundError(ref);
+							deleteStmt.run(ref);
+						} else insertStmt.run(ref, content);
+					})();
+					for (const hook of hooks ?? []) hook.onCommitted?.(txSnapshot);
+				} catch (e) {
+					for (const hook of hooks ?? []) hook.onAborted?.(txSnapshot);
+					throw e;
+				}
+			},
+			rollback() {
+				if (committed) return;
+				committed = true;
+				const txSnapshot = freezePending(pending);
+				for (const hook of hooks ?? []) hook.onAborted?.(txSnapshot);
+			}
+		};
+	}
+	return {
+		read(ref) {
+			validateRefName(ref);
+			return selectStmt.get(ref)?.target ?? null;
+		},
+		write(ref, content) {
+			validateRefName(ref);
+			insertStmt.run(ref, content.trimEnd());
+		},
+		delete(ref) {
+			validateRefName(ref);
+			if (!selectExistsStmt.get(ref)) throw new RefNotFoundError(ref);
+			deleteStmt.run(ref);
+		},
+		list(prefix) {
+			validateRefPrefix(prefix);
+			const end = prefix + "";
+			return listPrefixStmt.all(prefix, end).map((row) => row.name);
+		},
+		listAll() {
+			return listAllStmt.all().map((row) => row.name);
+		},
+		beginTransaction
+	};
+}
+/**
+* 将 pending Map 冻结为只读快照
+*/
+function freezePending(pending) {
+	const writes = [];
+	const deletes = [];
+	for (const [ref, content] of pending) if (content === null) deletes.push({ ref });
+	else writes.push({
+		ref,
+		content
+	});
+	return Object.freeze({
+		pendingCount: pending.size,
+		writes: Object.freeze(writes),
+		deletes: Object.freeze(deletes)
+	});
+}
+//#endregion
+export { createSqliteRefStore };

package/dist/remote/http.d.mts

@@ -0,0 +1,51 @@
+import { RemoteSource } from "./types.mjs";
+import { RefAdvertisement } from "../transport/protocol/types.mjs";
+import { LsRefsEntry, V2CapabilityAdvertisement } from "../transport/client/upload-pack/types.mjs";
+import { LsRefsOptions } from "../transport/client/upload-pack/ls-refs.mjs";
+import { ObjectInfoQueryResult } from "../transport/client/upload-pack/object-info.mjs";
+
+//#region src/remote/http.d.ts
+/**
+ * 远端 HTTP 查询接口
+ */
+interface HttpRemote {
+  /** 远端来源配置 */
+  readonly source: Readonly<RemoteSource>;
+  /** 读取 v2 能力广告 */
+  advertise(): Promise<V2CapabilityAdvertisement>;
+  /** 原样执行 ls-refs 查询 */
+  listRefs(options?: LsRefsOptions): Promise<LsRefsEntry[]>;
+  /** 读取适合高层 API 使用的 ref 快照 */
+  readRefAdvertisement(): Promise<RefAdvertisement>;
+  /** 查询对象元数据（协议 v2 object-info） */
+  fetchObjectInfo(oids: string[]): Promise<ObjectInfoQueryResult>;
+}
+/**
+ * 创建基于 Smart HTTP 的远端查询对象
+ *
+ * 适用于只依赖远端 URL / 认证信息的查询，
+ * 例如 refs 快照和 object-info，不需要本地 repo 上下文。
+ *
+ * @param source - 远端来源
+ * @returns 远端查询对象
+ *
+ * @example
+ * ```ts
+ * import { createHttpRemote } from "nano-git/remote/http";
+ *
+ * const remote = createHttpRemote({
+ *   url: "https://github.com/user/repo.git",
+ * });
+ *
+ * const snapshot = await remote.readRefAdvertisement();
+ * const info = await remote.fetchObjectInfo([
+ *   "95d09f2b10159347eece71399a7e2e907ea3df4f",
+ * ]);
+ *
+ * console.log(snapshot.defaultBranch);
+ * console.log(info.objects[0]?.size);
+ * ```
+ */
+declare function createHttpRemote(source: RemoteSource): HttpRemote;
+//#endregion
+export { HttpRemote, createHttpRemote };