nano-git 0.1.0

package/dist/repository/import/import-session-types.d.mts

@@ -0,0 +1,280 @@
+import { SHA1 } from "../../core/types.mjs";
+import { RefAdvertisement, RemoteRef } from "../../transport/protocol/types.mjs";
+
+//#region src/repository/import/import-session-types.d.ts
+/**
+ * 远端 Git 数据来源
+ *
+ * 只描述"从哪里读"，不描述"写到哪里"。
+ * ImportSource 不包含命名空间映射规则。
+ */
+interface ImportSource {
+  /** 远端仓库 URL */
+  readonly url: string;
+  /** 认证 token（用于 bearer 或 basic auth） */
+  readonly token?: string;
+  /** 自定义请求头 */
+  readonly headers?: Record<string, string>;
+}
+/**
+ * 远端 ref 视图
+ *
+ * 一个可命名、可复用、冻结的远端 ref 集合。
+ * view 是冻结集合，不是活查询。
+ * view 可以被多个物化步骤复用。
+ */
+interface ImportView {
+  /** 视图包含的远端 ref 列表（冻结快照） */
+  readonly refs: readonly RemoteRef[];
+  /**
+   * 通过谓词过滤当前视图
+   *
+   * @param predicate - 过滤谓词，返回 true 的 ref 保留
+   * @returns 新的 ImportView
+   */
+  where(predicate: (ref: RemoteRef) => boolean): ImportView;
+  /**
+   * 排除匹配指定 glob 模式的 ref
+   *
+   * @param pattern - glob 模式，如 "refs/tags/*beta*"
+   * @returns 新的 ImportView
+   */
+  exclude(pattern: string): ImportView;
+  /**
+   * 与另一个 view 取并集
+   *
+   * @param other - 另一个 view
+   * @returns 新的 ImportView（含两个 view 的 refs，去重保留首次出现的 ref）
+   */
+  union(other: ImportView): ImportView;
+  /**
+   * 为当前视图命名
+   *
+   * 命名后的 view 可用于 plan 阶段引用。
+   *
+   * @param label - 视图名称
+   * @returns NamedImportView
+   */
+  name(label: string): NamedImportView;
+}
+/**
+ * 命名的远端 ref 视图
+ *
+ * 在 ImportView 基础上增加 label 属性，用于 plan 阶段的语义引用。
+ */
+interface NamedImportView extends ImportView {
+  /** 视图名称 */
+  readonly label: string;
+}
+/**
+ * Ref 更新策略
+ */
+type RefUpdatePolicy = {
+  mode: "fast-forward";
+} | {
+  mode: "replace";
+} | {
+  mode: "create-only";
+} | {
+  mode: "mirror";
+};
+/**
+ * 命名空间物化选项
+ */
+interface NamespaceMaterializationOptions {
+  readonly policy?: RefUpdatePolicy;
+  readonly prune?: boolean;
+}
+/**
+ * Branch 物化选项
+ */
+interface BranchMaterializationOptions {
+  readonly policy?: RefUpdatePolicy;
+}
+/**
+ * Tag 物化选项
+ */
+interface TagMaterializationOptions {
+  readonly policy?: RefUpdatePolicy;
+}
+/**
+ * HEAD 物化选项
+ *
+ * setHead() 只能绑定到同一 plan 中已物化出的 `refs/heads/*`。
+ * `detach` 仅改变 HEAD 最终写入方式，不放宽目标命名空间。
+ */
+interface HeadMaterializationOptions {
+  readonly detach?: boolean;
+}
+/**
+ * Ref 物化构建器
+ */
+interface RefMaterializationBuilder {
+  toNamespace(targetPattern: string, options?: NamespaceMaterializationOptions): ImportPlanBuilder;
+  toBranch(branchName: string, options?: BranchMaterializationOptions): ImportPlanBuilder;
+  toTag(tagName: string, options?: TagMaterializationOptions): ImportPlanBuilder;
+  setHead(options?: HeadMaterializationOptions): ImportPlanBuilder;
+}
+/**
+ * 导入计划构建器
+ */
+interface ImportPlanBuilder {
+  materialize(view: ImportView): RefMaterializationBuilder;
+  preview(): Promise<ImportPreview>;
+  apply(): Promise<ImportApplyResult>;
+}
+/**
+ * 计划中的远端 ref 项
+ */
+interface PlannedRemoteRef {
+  readonly remoteRef: RemoteRef;
+  readonly localTarget: string;
+  readonly policy: RefUpdatePolicy;
+  readonly viewLabel?: string;
+}
+/**
+ * 本地前置条件
+ */
+interface LocalPrecondition {
+  readonly refName: string;
+  readonly expectedHash: SHA1 | null;
+  /**
+   * 原始 ref 值快照
+   *
+   * 用于 HEAD 这类可能是符号引用的特殊 ref。
+   * 普通 hash ref 通常不需要此字段。
+   */
+  readonly expectedValue?: string | null;
+  /**
+   * 命名空间快照前缀
+   *
+   * 用于 prune ownership 场景。
+   * 当此字段存在时，表示该前置条件校验的是整个命名空间下的 ref 集合，
+   * 而不是单个 ref。
+   */
+  readonly namespacePrefix?: string;
+  /**
+   * 命名空间 ownership 模式
+   *
+   * 当 prune 目标不是简单的前缀投影（例如 `refs/mirrors/*-backup`）时，
+   * 需要记录完整目标模式，以便 apply() 按同一集合重新校验和 prune。
+   */
+  readonly namespacePattern?: string;
+  /**
+   * 命名空间内全部 ref 的原始值快照
+   *
+   * 与 namespacePrefix 配合使用，用于检测 preview() 后
+   * 该命名空间下 ref 的新增、删除或内容漂移。
+   * 若存在 namespacePattern，则按完整模式而不是简单前缀匹配。
+   */
+  readonly expectedRefs?: readonly {
+    readonly refName: string;
+    readonly expectedValue: string | null;
+  }[];
+}
+/**
+ * 计划中的 ref 操作
+ */
+interface PlannedRefOperation {
+  readonly localRef: string;
+  readonly newHash: SHA1;
+  readonly policy: RefUpdatePolicy;
+  readonly viewLabel?: string;
+}
+/**
+ * 计划中的 HEAD 操作
+ *
+ * targetRef 始终是同一计划内已物化成功的本地 branch ref，
+ * 且必须位于 `refs/heads/*`。
+ */
+interface PlannedHeadOperation {
+  readonly targetRef: string;
+  readonly detach: boolean;
+  readonly viewLabel?: string;
+}
+/**
+ * 计划中的 ref 删除
+ */
+interface PlannedRefDeletion {
+  readonly refName: string;
+  readonly reason: string;
+  readonly namespacePattern: string;
+  readonly viewLabel?: string;
+}
+/**
+ * 导入诊断信息
+ */
+interface ImportDiagnostic {
+  readonly level: "info" | "warn" | "error";
+  readonly message: string;
+  readonly refName?: string;
+}
+/**
+ * 导入预览结果
+ *
+ * preview() 的目标是明确展示将会发生什么，
+ * 让调用者在 apply() 前有完整的认识。
+ */
+interface ImportPreview {
+  readonly remoteSnapshot: RefAdvertisement;
+  readonly selectedRefs: readonly PlannedRemoteRef[];
+  readonly objectRoots: readonly SHA1[];
+  readonly prefetchedObjects: number;
+  readonly localPreconditions: readonly LocalPrecondition[];
+  readonly refOperations: readonly PlannedRefOperation[];
+  readonly headOperation?: PlannedHeadOperation;
+  readonly pruneOperations: readonly PlannedRefDeletion[];
+  readonly diagnostics: readonly ImportDiagnostic[];
+  readonly canApply: boolean;
+}
+/**
+ * 导入执行结果
+ */
+interface ImportApplyResult {
+  readonly importedObjects: number;
+  readonly updatedRefs: ReadonlyMap<string, SHA1>;
+  readonly deletedRefs: readonly string[];
+  readonly headTarget?: string;
+}
+/**
+ * 导入会话
+ *
+ * 一次冻结的远端快照。
+ * 在创建时拉取一次 advertisement，所有派生 view 和 plan 都基于该快照。
+ * 想刷新远端状态时，必须重新创建 session。
+ */
+interface ImportSession {
+  readonly source: ImportSource;
+  readonly advertisement: RefAdvertisement;
+  select(pattern: string): ImportView;
+  selectRefs(patterns: readonly string[]): ImportView;
+  defaultBranch(): ImportView;
+  headTarget(): ImportView;
+  allRefs(): ImportView;
+  plan(): ImportPlanBuilder;
+}
+/**
+ * 仓库导入操作
+ */
+interface RepoImportOperations {
+  /**
+   * 打开一次导入会话
+   *
+   * 创建时自动拉取远端 advertisement。
+   * 会话及其所有派生 view 都是基于该快照的冻结视图。
+   *
+   * @param source - 导入源配置
+   * @returns ImportSession
+   *
+   * @example
+   * ```ts
+   * const session = await repo.openImportSession({
+   *   url: "https://example.com/repo.git",
+   * });
+   * const branches = session.select("refs/heads/*");
+   * ```
+   */
+  openImportSession(source: ImportSource): Promise<ImportSession>;
+}
+//#endregion
+export { RepoImportOperations };

package/dist/repository/import/import-session.mjs

@@ -0,0 +1,96 @@
+import { createV2HttpTransport } from "../../transport/client/upload-pack/http.mjs";
+import { lsRefs, lsRefsToRefAdvertisement } from "../../transport/client/upload-pack/ls-refs.mjs";
+import { matchRefGlob } from "./import-glob.mjs";
+import { createImportView } from "./import-view.mjs";
+import { createPlanBuilder } from "./import-plan-builder.mjs";
+//#region src/repository/import/import-session.ts
+/**
+* Import Session 实现
+*
+* 包含 session 创建和仓库级别导入操作工厂。
+* 使用 Git Wire 协议 v2 ls-refs + fetch 获取远端数据。
+*/
+/**
+* 创建 ImportSession
+*
+* @param source - 导入源配置
+* @param backend - 仓库后端
+* @param advertisement - 已获取的远端广告快照
+* @returns ImportSession
+*/
+function createImportSession(source, backend, advertisement, transportFactory, v2Transport) {
+	const frozenSource = Object.freeze({
+		url: source.url,
+		token: source.token,
+		headers: source.headers ? Object.freeze({ ...source.headers }) : void 0
+	});
+	const frozenRefs = Object.freeze(advertisement.refs.map((ref) => Object.freeze({ ...ref })));
+	const frozenAdvertisement = Object.freeze({
+		...advertisement,
+		refs: frozenRefs,
+		capabilities: Object.freeze({ ...advertisement.capabilities })
+	});
+	const allRefs = frozenAdvertisement.refs;
+	return {
+		source: frozenSource,
+		get advertisement() {
+			return frozenAdvertisement;
+		},
+		select(pattern) {
+			return createImportView(allRefs.filter((ref) => matchRefGlob(pattern, ref.name)));
+		},
+		selectRefs(patterns) {
+			const seen = /* @__PURE__ */ new Set();
+			const result = [];
+			for (const pattern of patterns) for (const ref of allRefs) if (matchRefGlob(pattern, ref.name) && !seen.has(ref.name)) {
+				seen.add(ref.name);
+				result.push(ref);
+			}
+			return createImportView(result);
+		},
+		defaultBranch() {
+			if (!frozenAdvertisement.defaultBranch) return createImportView([]);
+			const ref = allRefs.find((r) => r.name === frozenAdvertisement.defaultBranch);
+			return createImportView(ref ? [ref] : []);
+		},
+		headTarget() {
+			const headRef = allRefs.find((r) => r.name === "HEAD");
+			if (!headRef?.symrefTarget) return createImportView([]);
+			const target = allRefs.find((r) => r.name === headRef.symrefTarget);
+			return createImportView(target ? [target] : []);
+		},
+		allRefs() {
+			return createImportView(allRefs.filter((r) => r.name !== "HEAD"));
+		},
+		plan() {
+			return createPlanBuilder(backend, frozenAdvertisement, frozenSource, transportFactory, v2Transport);
+		}
+	};
+}
+/**
+* 创建仓库导入操作
+*
+* 使用 v2 Git Wire 协议，直接构造 v2 transport 并通过 ls-refs 获取远端引用。
+*
+* @param backend - 仓库后端
+* @returns RepoImportOperations
+*/
+function createRepoImportOperations(backend, transportFactory, testV2Transport) {
+	return { async openImportSession(source) {
+		const v2Transport = testV2Transport ?? createV2HttpTransport(source.url, {
+			token: source.token,
+			headers: source.headers
+		});
+		return createImportSession(source, backend, lsRefsToRefAdvertisement(await lsRefs(v2Transport, {
+			symrefs: true,
+			peel: true,
+			refPrefixes: [
+				"HEAD",
+				"refs/heads/",
+				"refs/tags/"
+			]
+		})), transportFactory, v2Transport);
+	} };
+}
+//#endregion
+export { createRepoImportOperations };

package/dist/repository/import/import-view.mjs

@@ -0,0 +1,133 @@
+import { matchRefGlob } from "./import-glob.mjs";
+//#region src/repository/import/import-view.ts
+/**
+* Import View 实现
+*
+* 提供远端 ref 视图的创建和操作功能，包括视图过滤、排除、合并和命名，
+* 以及路径前缀计算和命名空间目标解析。
+*/
+/**
+* 创建 ImportView
+*
+* @param refs - 冻结的远端 ref 列表
+* @param label - 可选的视图标签
+* @returns ImportView 或 NamedImportView
+*/
+function createImportView(refs, label) {
+	const frozenRefs = Object.freeze(refs.map((ref) => Object.freeze({ ...ref })));
+	return {
+		get refs() {
+			return frozenRefs;
+		},
+		where(predicate) {
+			return createImportView(frozenRefs.filter(predicate));
+		},
+		exclude(pattern) {
+			return createImportView(frozenRefs.filter((ref) => !matchRefGlob(pattern, ref.name)));
+		},
+		union(other) {
+			const seen = /* @__PURE__ */ new Set();
+			const merged = [];
+			for (const ref of frozenRefs) if (!seen.has(ref.name)) {
+				seen.add(ref.name);
+				merged.push(ref);
+			}
+			for (const ref of other.refs) if (!seen.has(ref.name)) {
+				seen.add(ref.name);
+				merged.push(ref);
+			}
+			return createImportView(merged);
+		},
+		name(n) {
+			return createImportView(frozenRefs, n);
+		},
+		get label() {
+			return label;
+		}
+	};
+}
+/**
+* 计算多个 ref 名称的最长公共路径前缀
+*
+* 结果保证以 `/` 结尾。单个 ref 时取其目录前缀。
+*
+* @param names - ref 名称列表
+* @returns 最长公共路径前缀（含末尾 /），如 "refs/heads/"
+*
+* @example
+* ```ts
+* longestCommonRefPrefix(["refs/heads/main", "refs/heads/develop"]); // "refs/heads/"
+* longestCommonRefPrefix(["refs/heads/main", "refs/tags/v1"]);       // "refs/"
+* ```
+*/
+function longestCommonRefPrefix(names) {
+	if (names.length === 0) return "";
+	if (names.length === 1) {
+		const lastSlash = names[0].lastIndexOf("/");
+		return lastSlash >= 0 ? names[0].slice(0, lastSlash + 1) : "";
+	}
+	let prefix = names[0];
+	for (let i = 1; i < names.length; i++) while (names[i].indexOf(prefix) !== 0) {
+		prefix = prefix.slice(0, -1);
+		if (prefix === "") return "";
+	}
+	const lastSlash = prefix.lastIndexOf("/");
+	return lastSlash >= 0 ? prefix.slice(0, lastSlash + 1) : "";
+}
+/**
+* 判断两个远端 ref 是否表示同一条广告项
+*
+* @param left - 左侧 ref
+* @param right - 右侧 ref
+* @returns 是否相同
+*/
+function isSameRemoteRef(left, right) {
+	return left.name === right.name && left.hash === right.hash && left.peeled === right.peeled && left.symrefTarget === right.symrefTarget;
+}
+/**
+* 解析命名空间物化：将 view 中的 refs 映射到目标命名空间
+*
+* 对每个 ref，计算其相对于 view 公共前缀的偏移，
+* 并用该偏移替换目标模式中的 `*`。
+*
+* @param refs - view 中的远端 refs
+* @param targetPattern - 目标模式，如 "refs/mirrors/upstream/*"
+* @returns 映射结果列表
+*
+* @example
+* ```ts
+* const targets = resolveNamespaceTargets(
+*   [refs/heads/main, refs/heads/develop],
+*   "refs/mirrors/upstream/*",
+* );
+* // => [{ localRef: "refs/mirrors/upstream/main" }, { localRef: "refs/mirrors/upstream/develop" }]
+* ```
+*/
+function resolveNamespaceTargets(refs, targetPattern) {
+	if (refs.length === 0) return [];
+	if (!targetPattern.includes("*")) return refs.map((r) => ({
+		remoteRef: r,
+		localRef: targetPattern
+	}));
+	const [beforeStar, afterStar] = targetPattern.split("*", 2);
+	const commonPrefix = longestCommonRefPrefix(refs.map((r) => r.name));
+	const after = afterStar ?? "";
+	return refs.map((r) => {
+		return {
+			remoteRef: r,
+			localRef: `${beforeStar}${r.name.slice(commonPrefix.length)}${after}`
+		};
+	});
+}
+/**
+* 截取命名空间目标模式的固定前缀
+*
+* @param targetPattern - 目标模式
+* @returns `*` 之前的固定前缀；无 `*` 时返回 null
+*/
+function getNamespacePatternPrefix(targetPattern) {
+	const starIdx = targetPattern.indexOf("*");
+	return starIdx >= 0 ? targetPattern.slice(0, starIdx) : null;
+}
+//#endregion
+export { createImportView, getNamespacePatternPrefix, isSameRemoteRef, resolveNamespaceTargets };

package/dist/repository/memory.d.mts

@@ -0,0 +1,17 @@
+import { Repository } from "./types.mjs";
+
+//#region src/repository/memory.d.ts
+/**
+ * 创建内存仓库
+ *
+ * @returns 仓库实例
+ *
+ * @example
+ * ```ts
+ * const repo = createMemoryRepository();
+ * repo.createBranch("main", repo.createTree([]));
+ * ```
+ */
+declare function createMemoryRepository(): Repository;
+//#endregion
+export { createMemoryRepository };

package/dist/repository/memory.mjs

@@ -0,0 +1,33 @@
+import { createMemoryRepositoryBackend } from "../backend/memory-backend.mjs";
+import { createRepository } from "./create.mjs";
+//#region src/repository/memory.ts
+/**
+* 内存仓库便捷创建函数
+*
+* 一键创建完全在内存中的 Git 仓库，无需任何文件系统操作。
+* 适用于测试和临时操作场景。
+*
+* @example
+* ```ts
+* import { createMemoryRepository } from "nano-git/repository/memory";
+*
+* const repo = createMemoryRepository();
+* const hash = repo.writeBlob(Buffer.from("hello world"));
+* ```
+*/
+/**
+* 创建内存仓库
+*
+* @returns 仓库实例
+*
+* @example
+* ```ts
+* const repo = createMemoryRepository();
+* repo.createBranch("main", repo.createTree([]));
+* ```
+*/
+function createMemoryRepository() {
+	return createRepository(createMemoryRepositoryBackend());
+}
+//#endregion
+export { createMemoryRepository };

package/dist/repository/ops/fetch-operations.mjs

@@ -0,0 +1,20 @@
+import { runFetchToUrl } from "./fetch-url.mjs";
+//#region src/repository/ops/fetch-operations.ts
+/**
+* Fetch 操作编排
+*
+* repository 层只保留显式 URL 的 fetch 入口。
+*/
+/**
+* 创建仓库 fetch 操作集合
+*
+* @param backend - 仓库后端
+* @returns fetch 操作集合
+*/
+function createFetchRepositoryOperations(backend) {
+	return { async fetch(url, options) {
+		return runFetchToUrl(backend, url, options);
+	} };
+}
+//#endregion
+export { createFetchRepositoryOperations };

package/dist/repository/ops/fetch-types.d.mts

@@ -0,0 +1,82 @@
+import { SHA1 } from "../../core/types.mjs";
+
+//#region src/repository/ops/fetch-types.d.ts
+/**
+ * 仓库 fetch 操作选项
+ */
+interface RepositoryFetchOptions {
+  /**
+   * RefSpec 列表，格式如 "refs/heads/main:refs/heads/main"
+   * 传入后完全取代默认映射（远端所有 branches → refs/heads/* + tags → refs/tags/*）。
+   */
+  readonly refSpecs?: string[];
+  /**
+   * 仅 fetch 匹配指定 glob 模式的远端 refs（如 "refs/heads/feature/*"），
+   * 不 fetch 全部。不可与 refSpecs 同时使用。
+   */
+  readonly refPatterns?: string[];
+  /** 认证 token（用于 bearer 或 basic auth） */
+  readonly token?: string;
+  /** 自定义请求头 */
+  readonly headers?: Record<string, string>;
+  /** 不自动 fetch 远端 tags（对标 `git fetch --no-tags`） */
+  readonly noTags?: boolean;
+  /** 删除本地有但远端已不存在的 refs（对标 `git fetch --prune`） */
+  readonly prune?: boolean;
+  /** 强制更新（对标 `git fetch --force`，等价于所有 refspec 加 + 前缀） */
+  readonly force?: boolean;
+  /** 浅 fetch 深度（⚠️ ImportSession 当前不支持，传此值会静默忽略） */
+  readonly depth?: number;
+}
+/**
+ * 单条引用更新结果
+ */
+interface FetchRefUpdateResult {
+  /** 引用名称，如 "refs/heads/main" */
+  readonly refName: string;
+  /** 更新前的哈希 */
+  readonly oldHash: SHA1 | null;
+  /** 更新后的哈希 */
+  readonly newHash: SHA1 | null;
+  /** 是否成功 */
+  readonly success: boolean;
+  /** 是否强制更新 */
+  readonly forced: boolean;
+  /** 失败时的错误消息 */
+  readonly error?: string;
+}
+/**
+ * 仓库 fetch 操作结果
+ */
+interface RepositoryFetchResult {
+  /** 已更新的引用列表 */
+  readonly updatedRefs: readonly FetchRefUpdateResult[];
+  /** 导入的对象数量 */
+  readonly objectCount: number;
+  /** 服务端返回的进度消息 */
+  readonly progress: readonly string[];
+}
+/**
+ * 仓库 fetch 操作接口
+ */
+interface RepositoryFetchOperations {
+  /**
+   * 从远端仓库拉取 refs 和对象
+   *
+   * 等价于 `git fetch <url>`。
+   * 默认行为：拉取所有远端分支（fast-forward）+ 标签 + 设置 HEAD。
+   *
+   * @param url - 远端仓库 URL
+   * @param options - 可选参数
+   * @returns fetch 结果
+   *
+   * @example
+   * ```ts
+   * const result = await repo.fetch("https://github.com/user/repo.git");
+   * console.log(`Updated ${result.updatedRefs.length} refs`);
+   * ```
+   */
+  fetch(url: string, options?: RepositoryFetchOptions): Promise<RepositoryFetchResult>;
+}
+//#endregion
+export { RepositoryFetchOperations };