nano-git 0.1.0

package/dist/transport/client/upload-pack/ls-refs.mjs

@@ -0,0 +1,150 @@
+import { GitError } from "../../../core/errors.mjs";
+import { sha1 } from "../../../core/types.mjs";
+import { parsePktLines } from "../../protocol/pkt-line.mjs";
+//#region src/transport/client/upload-pack/ls-refs.ts
+/**
+* v2 ls-refs 命令
+*
+* 在 Git Wire 协议 v2 中，ls-refs 替代了 v1 的 ref advertisement。
+* 服务端通过独立的 `ls-refs` 命令返回引用列表。
+*
+* 请求格式：
+* ```
+* command=ls-refs\n
+* agent=nano-git/0.1\n
+* 0001
+* symrefs\n
+* peel\n
+* ref-prefix refs/heads/\n
+* 0000
+* ```
+*
+* 响应格式：
+* ```
+* <oid> <refname>[ <attr>...]\n
+* ...
+* 0000
+* ```
+*
+* @see https://git-scm.com/docs/protocol-v2#_ls_refs
+*/
+/**
+* ls-refs 命令错误
+*/
+var LsRefsError = class extends GitError {
+	constructor(message) {
+		super(`ls-refs error: ${message}`);
+		this.name = "LsRefsError";
+	}
+};
+/**
+* 执行 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/"],
+* });
+* ```
+*/
+async function lsRefs(transport, options) {
+	const args = [];
+	if (options?.symrefs) args.push("symrefs");
+	if (options?.peel) args.push("peel");
+	if (options?.unborn) args.push("unborn");
+	if (options?.refPrefixes) for (const prefix of options.refPrefixes) args.push(`ref-prefix ${prefix}`);
+	return parseLsRefsResponse(await transport.command("ls-refs", args));
+}
+/**
+* 解析 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"
+* ```
+*/
+function parseLsRefsResponse(data) {
+	const lines = parsePktLines(data);
+	const entries = [];
+	for (const line of lines) {
+		if (line.type !== "data") continue;
+		const text = line.payload.toString("utf-8").trim();
+		if (text.length === 0) continue;
+		const spaceIdx = text.indexOf(" ");
+		if (spaceIdx === -1) continue;
+		const oid = text.substring(0, spaceIdx);
+		const parts = text.substring(spaceIdx + 1).trim().split(" ");
+		const entry = {
+			oid,
+			refname: parts[0]
+		};
+		for (let i = 1; i < parts.length; i++) {
+			const attr = parts[i];
+			if (attr.startsWith("symref-target:")) entry.symrefTarget = attr.substring(14);
+			else if (attr.startsWith("peeled:")) entry.peeled = attr.substring(7);
+		}
+		entries.push(entry);
+	}
+	return entries;
+}
+/**
+* 将 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
+* ```
+*/
+function lsRefsToRefAdvertisement(entries) {
+	const refs = [];
+	let defaultBranch;
+	const peeledMap = /* @__PURE__ */ new Map();
+	for (const entry of entries) if (entry.peeled) {
+		const baseName = entry.refname.endsWith("^{}") ? entry.refname.slice(0, -3) : entry.refname;
+		peeledMap.set(baseName, entry.peeled);
+	}
+	for (const entry of entries) {
+		if (entry.oid === "unborn") continue;
+		if (entry.refname.endsWith("^{}")) continue;
+		const ref = {
+			hash: sha1(entry.oid),
+			name: entry.refname
+		};
+		if (entry.symrefTarget) ref.symrefTarget = entry.symrefTarget;
+		const peeled = peeledMap.get(entry.refname);
+		if (peeled) ref.peeled = sha1(peeled);
+		refs.push(ref);
+		if (entry.refname === "HEAD" && entry.symrefTarget) defaultBranch = entry.symrefTarget;
+	}
+	if (!defaultBranch && refs.length > 0) {
+		const mainBranch = refs.find((r) => r.name === "refs/heads/main" || r.name === "refs/heads/master");
+		if (mainBranch) defaultBranch = mainBranch.name;
+	}
+	return {
+		capabilities: {},
+		refs,
+		defaultBranch
+	};
+}
+//#endregion
+export { LsRefsError, lsRefs, lsRefsToRefAdvertisement, parseLsRefsResponse };

package/dist/transport/client/upload-pack/object-info.d.mts

@@ -0,0 +1,65 @@
+import { GitError } from "../../../core/errors.mjs";
+import { V2GitServiceTransport } from "./types.mjs";
+
+//#region src/transport/client/upload-pack/object-info.d.ts
+/**
+ * object-info 命令错误
+ */
+declare class ObjectInfoError extends GitError {
+  constructor(message: string);
+}
+/**
+ * object-info 查询结果条目
+ */
+interface ObjectInfoResult {
+  readonly oid: string;
+  readonly size?: number;
+}
+/**
+ * object-info 查询响应
+ */
+interface ObjectInfoQueryResult {
+  readonly attrs: string[];
+  readonly objects: ObjectInfoResult[];
+}
+/**
+ * 执行 object-info 命令
+ *
+ * 批量查询远端对象的元数据（如 size），无需下载对象内容。
+ *
+ * @param transport - v2 传输接口
+ * @param oids - 要查询的 OID 列表
+ * @returns 查询结果
+ *
+ * @example
+ * ```ts
+ * const result = await objectInfo(transport, [
+ *   "95d09f2b10159347eece71399a7e2e907ea3df4f",
+ * ]);
+ * console.log(result.objects[0]?.size); // 文件大小（字节）
+ * ```
+ */
+declare function objectInfo(transport: V2GitServiceTransport, oids: string[]): Promise<ObjectInfoQueryResult>;
+/**
+ * 解析 object-info 响应
+ *
+ * 格式：
+ * ```
+ * size\n
+ * <oid1> <size1>\n
+ * <oid2> <size2>\n
+ * 0000
+ * ```
+ *
+ * @param data - 原始响应数据
+ * @returns 解析后的查询结果
+ *
+ * @example
+ * ```ts
+ * const result = parseObjectInfoResponse(response);
+ * console.log(result.attrs); // ["size"]
+ * ```
+ */
+declare function parseObjectInfoResponse(data: Buffer): ObjectInfoQueryResult;
+//#endregion
+export { ObjectInfoError, ObjectInfoQueryResult, ObjectInfoResult, objectInfo, parseObjectInfoResponse };

package/dist/transport/client/upload-pack/object-info.mjs

@@ -0,0 +1,111 @@
+import { GitError } from "../../../core/errors.mjs";
+import { parsePktLines } from "../../protocol/pkt-line.mjs";
+//#region src/transport/client/upload-pack/object-info.ts
+/**
+* v2 object-info 命令
+*
+* 在 Git Wire 协议 v2 中，object-info 命令用于批量查询对象信息（如 size），
+* 而不需要实际获取对象内容。主要用于 partial clone 场景。
+*
+* 请求格式：
+* ```
+* command=object-info\n
+* 0001
+* size\n
+* oid <oid1>\n
+* oid <oid2>\n
+* 0000
+* ```
+*
+* 响应格式：
+* ```
+* size\n
+* <oid1> <size1>\n
+* <oid2> <size2>\n
+* 0000
+* ```
+*
+* @see https://git-scm.com/docs/protocol-v2#_object_info
+*/
+/**
+* object-info 命令错误
+*/
+var ObjectInfoError = class extends GitError {
+	constructor(message) {
+		super(`object-info error: ${message}`);
+		this.name = "ObjectInfoError";
+	}
+};
+/**
+* 执行 object-info 命令
+*
+* 批量查询远端对象的元数据（如 size），无需下载对象内容。
+*
+* @param transport - v2 传输接口
+* @param oids - 要查询的 OID 列表
+* @returns 查询结果
+*
+* @example
+* ```ts
+* const result = await objectInfo(transport, [
+*   "95d09f2b10159347eece71399a7e2e907ea3df4f",
+* ]);
+* console.log(result.objects[0]?.size); // 文件大小（字节）
+* ```
+*/
+async function objectInfo(transport, oids) {
+	if (oids.length === 0) throw new ObjectInfoError("No OIDs specified for object-info");
+	const args = ["size"];
+	for (const oid of oids) args.push(`oid ${oid}`);
+	return parseObjectInfoResponse(await transport.command("object-info", args));
+}
+/**
+* 解析 object-info 响应
+*
+* 格式：
+* ```
+* size\n
+* <oid1> <size1>\n
+* <oid2> <size2>\n
+* 0000
+* ```
+*
+* @param data - 原始响应数据
+* @returns 解析后的查询结果
+*
+* @example
+* ```ts
+* const result = parseObjectInfoResponse(response);
+* console.log(result.attrs); // ["size"]
+* ```
+*/
+function parseObjectInfoResponse(data) {
+	const pktLines = parsePktLines(data);
+	const objects = [];
+	let attrs = [];
+	for (const line of pktLines) {
+		if (line.type !== "data") continue;
+		const text = line.payload.toString("utf-8").trim();
+		if (text.length === 0) continue;
+		if (attrs.length === 0) {
+			attrs = text.split(" ");
+			continue;
+		}
+		const spaceIdx = text.indexOf(" ");
+		if (spaceIdx === -1) objects.push({ oid: text });
+		else {
+			const oid = text.substring(0, spaceIdx);
+			const sizeStr = text.substring(spaceIdx + 1).trim();
+			objects.push({
+				oid,
+				size: parseInt(sizeStr, 10)
+			});
+		}
+	}
+	return {
+		attrs,
+		objects
+	};
+}
+//#endregion
+export { ObjectInfoError, objectInfo, parseObjectInfoResponse };

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

@@ -0,0 +1,153 @@
+//#region src/transport/client/upload-pack/types.d.ts
+/**
+ * Git Wire 协议 v2 类型定义
+ *
+ * 定义了协议 v2 特有的类型：能力广告、命令式传输接口等。
+ * 协议无关的共享类型见 protocol/types.ts。
+ */
+/**
+ * v2 能力广告中的单个命令条目
+ *
+ * 表示服务端广告的 v2 命令及附加特性。
+ *
+ * @example
+ * ```ts
+ * const cmd: V2CommandEntry = {
+ *   name: "fetch",
+ *   features: ["shallow", "ref-in-want"],
+ * };
+ * ```
+ */
+interface V2CommandEntry {
+  /** 命令名称，如 "ls-refs"、"fetch"、"push"、"object-info" */
+  readonly name: string;
+  /** 命令附加特性列表（在 capability 值中声明） */
+  readonly features: string[];
+}
+/**
+ * v2 能力广告（服务端响应）
+ *
+ * 对应协议 v2 的能力广告格式：
+ * ```
+ * version 2\n
+ * ls-refs\n
+ * fetch=shallow ref-in-want\n
+ * push\n
+ * object-info\n
+ * agent=nano-git/0.1\n
+ * 0000
+ * ```
+ */
+interface V2CapabilityAdvertisement {
+  /** 服务端能力键值对 */
+  readonly capabilities: Record<string, string | true>;
+  /** 服务端支持的 v2 命令列表 */
+  readonly commands: V2CommandEntry[];
+  /** 服务端 agent 字符串 */
+  readonly agent?: string;
+}
+/**
+ * v2 Git 服务传输接口
+ *
+ * 与 v1 的 GitServiceTransport 不同，v2 是命令式的。
+ * - advertise() 只返回能力广告，不含 refs
+ * - command() 发送单个命令并返回原始响应
+ */
+interface V2GitServiceTransport {
+  /** 获取能力广告 */
+  advertise(): Promise<V2CapabilityAdvertisement>;
+  /**
+   * 执行 v2 命令
+   *
+   * @param command - 命令名称，如 "ls-refs"、"fetch"
+   * @param args - 命令参数列表
+   * @param capabilities - 本次请求携带的能力列表（不含 agent）
+   * @param body - 额外的原始 body 数据（如 push 的 packfile）
+   */
+  command(command: string, args?: string[], capabilities?: string[], body?: Buffer): Promise<Buffer>;
+}
+/**
+ * ls-refs 输出条目
+ *
+ * 对应 v2 ls-refs 响应中的单行 ref。
+ * ```
+ * <obj-id> SP <refname> [SP <ref-attribute> ...] LF
+ * ```
+ */
+interface LsRefsEntry {
+  /** 对象哈希，unborn 分支时为 "unborn" */
+  readonly oid: string;
+  /** 引用全名 */
+  readonly refname: string;
+  /** 符号引用目标（如有） */
+  readonly symrefTarget?: string;
+  /** peeled 对象哈希（如有） */
+  readonly peeled?: string;
+}
+/**
+ * v2 fetch 请求参数
+ */
+interface V2FetchRequest {
+  readonly wants: string[];
+  readonly haves?: string[];
+  readonly done?: boolean;
+  readonly wantRefs?: string[];
+  readonly thinPack?: boolean;
+  readonly noProgress?: boolean;
+  readonly includeTag?: boolean;
+  readonly ofsDelta?: boolean;
+  readonly shallow?: string[];
+  readonly deepen?: number;
+  readonly deepenRelative?: boolean;
+  readonly deepenSince?: number;
+  readonly deepenNot?: string[];
+  readonly filter?: string;
+  readonly sidebandAll?: boolean;
+  readonly waitForDone?: boolean;
+}
+/**
+ * v2 fetch 响应
+ *
+ * 响应包含多个由 delimiter (0001) 分隔的节。
+ */
+interface V2FetchResponse {
+  /** acknowledgments 节 */
+  readonly acknowledgments?: {
+    readonly nak?: boolean;
+    readonly acks: string[];
+    readonly ready?: boolean;
+  };
+  /** shallow-info 节 */
+  readonly shallowInfo?: {
+    readonly shallow: string[];
+    readonly unshallow: string[];
+  };
+  /** wanted-refs 节 */
+  readonly wantedRefs?: Array<{
+    oid: string;
+    refname: string;
+  }>;
+  /** packfile-uris 节 */
+  readonly packfileUris?: Array<{
+    oid: string;
+    uri: string;
+  }>;
+  /** 原始 packfile buffer */
+  readonly packfile?: Buffer;
+}
+/**
+ * object-info 结果条目
+ */
+interface ObjectInfoEntry {
+  readonly oid: string;
+  readonly size?: number;
+}
+/**
+ * object-info 响应
+ */
+interface ObjectInfoResponse {
+  readonly attrs: string[];
+  readonly objects: ObjectInfoEntry[];
+}
+//#endregion
+export { LsRefsEntry, ObjectInfoEntry, ObjectInfoResponse, V2CapabilityAdvertisement, V2CommandEntry, V2FetchRequest, V2FetchResponse, V2GitServiceTransport };

package/dist/transport/http/index.d.mts

@@ -0,0 +1,3 @@
+import { SmartHttpHandler } from "./types.mjs";
+import { createSmartHttpHandler } from "./smart-http.mjs";
+export { type SmartHttpHandler, createSmartHttpHandler };

package/dist/transport/http/index.mjs

@@ -0,0 +1,2 @@
+import { createSmartHttpHandler } from "./smart-http.mjs";
+export { createSmartHttpHandler };

package/dist/transport/http/smart-http.d.mts

@@ -0,0 +1,46 @@
+import { RepositoryBackend } from "../../backend/types.mjs";
+import { SmartHttpHandler } from "./types.mjs";
+
+//#region src/transport/http/smart-http.d.ts
+/**
+ * 创建 Smart HTTP 处理函数
+ *
+ * 类似 git-http-backend 的核心入口。
+ * 接收标准 Request，返回标准 Response，框架无关。
+ *
+ * @param backend - 仓库后端
+ * @returns HTTP 处理函数
+ *
+ * @example
+ * ```ts
+ * // Bun.serve — 直接作为 fetch 处理器
+ * import { createSmartHttpHandler } from "nano-git/transport/http";
+ * import { openRepository } from "nano-git/repository/file";
+ * Bun.serve({ port: 8080, fetch: createSmartHttpHandler(openRepository("/repo")) });
+ *
+ * // Node.js http
+ * import { createServer } from "node:http";
+ * const handler = createSmartHttpHandler(openRepository("/repo"));
+ * createServer(async (req, res) => {
+ *   const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+ *   const body = await new Promise<Buffer>((resolve) => {
+ *     const chunks: Buffer[] = [];
+ *     req.on("data", (c) => chunks.push(c));
+ *     req.on("end", () => resolve(Buffer.concat(chunks)));
+ *   });
+ *   const response = await handler(new Request(url, {
+ *     method: req.method,
+ *     headers: Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k, String(v)])),
+ *     body: req.method === "POST" ? body : undefined,
+ *   }));
+ *   res.writeHead(response.status, Object.fromEntries(response.headers));
+ *   res.end(Buffer.from(await response.arrayBuffer()));
+ * }).listen(8080);
+ *
+ * // Cloudflare Workers / Deno
+ * export default { fetch: createSmartHttpHandler(openRepository("./repo")) };
+ * ```
+ */
+declare function createSmartHttpHandler(backend: RepositoryBackend): SmartHttpHandler;
+//#endregion
+export { createSmartHttpHandler };