nano-git 0.1.0 → 0.2.1

package/dist/remote/http.mjs

@@ -0,0 +1,74 @@
+import { createV2HttpTransport } from "../transport/client/upload-pack/http.mjs";
+import { lsRefs, lsRefsToRefAdvertisement } from "../transport/client/upload-pack/ls-refs.mjs";
+import { objectInfo } from "../transport/client/upload-pack/object-info.mjs";
+//#region src/remote/http.ts
+/**
+* 基于 HTTP 的远端 Git 查询 API
+*
+* 将纯远端查询能力从 Repository 中拆出：
+* - refs 快照
+* - v2 object-info
+* - 协议能力广告
+*/
+/**
+* 创建基于 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);
+* ```
+*/
+function createHttpRemote(source) {
+	const frozenSource = Object.freeze({
+		url: source.url,
+		token: source.token,
+		headers: source.headers ? Object.freeze({ ...source.headers }) : void 0
+	});
+	const transport = createV2HttpTransport(frozenSource.url, {
+		token: frozenSource.token,
+		headers: frozenSource.headers
+	});
+	return {
+		source: frozenSource,
+		advertise() {
+			return transport.advertise();
+		},
+		listRefs(options) {
+			return lsRefs(transport, options);
+		},
+		async readRefAdvertisement() {
+			return lsRefsToRefAdvertisement(await lsRefs(transport, {
+				symrefs: true,
+				peel: true,
+				refPrefixes: [
+					"HEAD",
+					"refs/heads/",
+					"refs/tags/"
+				]
+			}));
+		},
+		fetchObjectInfo(oids) {
+			return objectInfo(transport, oids);
+		}
+	};
+}
+//#endregion
+export { createHttpRemote };

package/dist/remote/types.d.mts

@@ -0,0 +1,20 @@
+//#region src/remote/types.d.ts
+/**
+ * 远端来源类型定义
+ *
+ * 只描述"从哪里读"，不描述"写到哪里"。
+ * 可被远端查询 API 与仓库导入 API 共同复用。
+ */
+/**
+ * 远端 Git 数据来源
+ */
+interface RemoteSource {
+  /** 远端仓库 URL */
+  readonly url: string;
+  /** 认证 token（用于 bearer 或 basic auth） */
+  readonly token?: string;
+  /** 自定义请求头 */
+  readonly headers?: Record<string, string>;
+}
+//#endregion
+export { RemoteSource };

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

@@ -1,21 +1,8 @@
 import { SHA1 } from "../../core/types.mjs";
+import { RemoteSource } from "../../remote/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 视图
  *
@@ -244,7 +231,7 @@ interface ImportApplyResult {
  * 想刷新远端状态时，必须重新创建 session。
  */
 interface ImportSession {
-  readonly source: ImportSource;
+  readonly source: RemoteSource;
   readonly advertisement: RefAdvertisement;
   select(pattern: string): ImportView;
   selectRefs(patterns: readonly string[]): ImportView;
@@ -274,7 +261,7 @@ interface RepoImportOperations {
    * const branches = session.select("refs/heads/*");
    * ```
    */
-  openImportSession(source: ImportSource): Promise<ImportSession>;
+  openImportSession(source: RemoteSource): Promise<ImportSession>;
 }
 //#endregion
 export { RepoImportOperations };

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

@@ -1,7 +1,5 @@
 import { hashObject } from "../../core/hash-digest.mjs";
 import { readObject, writeObject } from "../../objects/raw.mjs";
-import { createV2HttpTransport } from "../../transport/client/upload-pack/http.mjs";
-import { objectInfo } from "../../transport/client/upload-pack/object-info.mjs";
 import { patchTree } from "../tree/tree-patch.mjs";
 //#region src/repository/ops/object-operations.ts
 /**
@@ -55,9 +53,6 @@ function createObjectRepositoryOperations(objects) {
 		},
 		patchTree(rootHash, ops) {
 			return patchTree(objects, rootHash, ops);
-		},
-		async fetchObjectInfo(url, oids, token) {
-			return objectInfo(createV2HttpTransport(url, { token }), oids);
 		}
 	};
 }

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

@@ -1,5 +1,4 @@
 import { GitAuthor, GitObject, SHA1, TreeEntry } from "../../core/types.mjs";
-import { ObjectInfoQueryResult } from "../../transport/client/upload-pack/object-info.mjs";
 import { TreePatchOp, TreePatchResult } from "../tree/tree-patch.mjs";
 
 //#region src/repository/ops/object-types.d.ts
@@ -67,26 +66,6 @@ interface RepositoryObjectOperations {
    * ```
    */
   patchTree(rootHash: SHA1, ops: TreePatchOp[]): TreePatchResult;
-  /**
-   * 查询远端对象信息（协议 v2 object-info）
-   *
-   * 批量查询远端对象的元数据（如 size），无需下载对象内容。
-   * 仅在远端支持 Git Wire 协议 v2 时可用。
-   *
-   * @param url - 远端仓库 URL
-   * @param oids - 要查询的 OID 列表
-   * @param token - 可选认证 token
-   * @returns 对象信息列表（含 size 等元数据）
-   *
-   * @example
-   * ```ts
-   * const result = await repo.fetchObjectInfo("https://github.com/user/repo", [
-   *   "95d09f2b10159347eece71399a7e2e907ea3df4f",
-   * ]);
-   * console.log(result.objects[0]?.size); // 文件大小
-   * ```
-   */
-  fetchObjectInfo(url: string, oids: string[], token?: string): Promise<ObjectInfoQueryResult>;
 }
 /**
  * 文件系统对象操作扩展

package/dist/repository/sqlite.d.mts

@@ -0,0 +1,28 @@
+import { CreateSqliteRepositoryBackendOptions } from "../backend/sqlite.mjs";
+import { Repository } from "./types.mjs";
+
+//#region src/repository/sqlite.d.ts
+/**
+ * 创建基于 SQLite 文件的持久化仓库
+ *
+ * 相比直接使用 createSqliteRepositoryBackend + createRepository，
+ * 此函数提供了更简洁的一步到位接口。
+ *
+ * @param dbPath - SQLite 数据库文件路径
+ * @param options - 可选参数（如 walMode）
+ * @returns 仓库实例（附带 [Symbol.dispose]()，可用 `using` 管理）
+ *
+ * @example
+ * ```ts
+ * // 使用 using 自动释放（推荐）
+ * using repo = createSqliteRepository("/tmp/repo.sqlite");
+ * repo.createBranch("main", repo.createTree([]));
+ * repo.writeBlob(Buffer.from("data"));
+ * // 作用域结束时自动关闭数据库连接
+ * ```
+ */
+declare function createSqliteRepository(dbPath: string, options?: CreateSqliteRepositoryBackendOptions): Repository & {
+  [Symbol.dispose](): void;
+};
+//#endregion
+export { createSqliteRepository };

package/dist/repository/sqlite.mjs

@@ -0,0 +1,45 @@
+import { createSqliteRepositoryBackend } from "../backend/sqlite.mjs";
+import { createRepository } from "./create.mjs";
+//#region src/repository/sqlite.ts
+/**
+* SQLite 仓库便捷创建函数
+*
+* 一键创建基于 SQLite 的持久化 Git 仓库。
+* 内部组合 createSqliteRepositoryBackend + createRepository，
+* 返回的 repo 自带 [Symbol.dispose]()，可用 `using` 管理生命周期。
+*
+* @example
+* ```ts
+* import { createSqliteRepository } from "nano-git/repository/sqlite";
+*
+* using repo = createSqliteRepository("/tmp/cache.sqlite");
+* const hash = repo.writeBlob(Buffer.from("hello world"));
+* // 作用域结束时自动 db.close()
+* ```
+*/
+/**
+* 创建基于 SQLite 文件的持久化仓库
+*
+* 相比直接使用 createSqliteRepositoryBackend + createRepository，
+* 此函数提供了更简洁的一步到位接口。
+*
+* @param dbPath - SQLite 数据库文件路径
+* @param options - 可选参数（如 walMode）
+* @returns 仓库实例（附带 [Symbol.dispose]()，可用 `using` 管理）
+*
+* @example
+* ```ts
+* // 使用 using 自动释放（推荐）
+* using repo = createSqliteRepository("/tmp/repo.sqlite");
+* repo.createBranch("main", repo.createTree([]));
+* repo.writeBlob(Buffer.from("data"));
+* // 作用域结束时自动关闭数据库连接
+* ```
+*/
+function createSqliteRepository(dbPath, options) {
+	const backend = createSqliteRepositoryBackend(dbPath, options);
+	const repo = createRepository(backend);
+	return Object.assign(repo, { [Symbol.dispose]: () => backend[Symbol.dispose]() });
+}
+//#endregion
+export { createSqliteRepository };

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

@@ -1,7 +1,7 @@
 import { LsRefsEntry, ObjectInfoEntry, ObjectInfoResponse, V2CapabilityAdvertisement, V2CommandEntry, V2FetchRequest, V2FetchResponse, V2GitServiceTransport } from "./client/upload-pack/types.mjs";
+import { LsRefsError, LsRefsOptions, lsRefs, lsRefsToRefAdvertisement, parseLsRefsResponse } from "./client/upload-pack/ls-refs.mjs";
 import { ObjectInfoError, ObjectInfoQueryResult, ObjectInfoResult, objectInfo, parseObjectInfoResponse } from "./client/upload-pack/object-info.mjs";
 import { V2CapabilityError, getCommandFeatures, hasCommand, parseV2CapabilityAdvertisement } from "./client/upload-pack/capability-advertisement.mjs";
 import { V2SmartHttpError, createV2HttpTransport } from "./client/upload-pack/http.mjs";
-import { LsRefsError, LsRefsOptions, lsRefs, lsRefsToRefAdvertisement, parseLsRefsResponse } from "./client/upload-pack/ls-refs.mjs";
 import { V2FetchError, V2FetchParams, parseV2FetchResponse, v2Fetch, v2FetchObjects } from "./client/upload-pack/fetch.mjs";
 export { type LsRefsEntry, LsRefsError, type LsRefsOptions, type ObjectInfoEntry, ObjectInfoError, type ObjectInfoQueryResult, type ObjectInfoResponse, type ObjectInfoResult, type V2CapabilityAdvertisement, V2CapabilityError, type V2CommandEntry, V2FetchError, type V2FetchParams, type V2FetchRequest, type V2FetchResponse, type V2GitServiceTransport, V2SmartHttpError, createV2HttpTransport, getCommandFeatures, hasCommand, lsRefs, lsRefsToRefAdvertisement, objectInfo, parseLsRefsResponse, parseObjectInfoResponse, parseV2CapabilityAdvertisement, parseV2FetchResponse, v2Fetch, v2FetchObjects };

package/dist/transport/upload-pack.mjs

@@ -1,6 +1,6 @@
 import { V2CapabilityError, getCommandFeatures, hasCommand, parseV2CapabilityAdvertisement } from "./client/upload-pack/capability-advertisement.mjs";
 import { V2SmartHttpError, createV2HttpTransport } from "./client/upload-pack/http.mjs";
 import { LsRefsError, lsRefs, lsRefsToRefAdvertisement, parseLsRefsResponse } from "./client/upload-pack/ls-refs.mjs";
-import { V2FetchError, parseV2FetchResponse, v2Fetch, v2FetchObjects } from "./client/upload-pack/fetch.mjs";
 import { ObjectInfoError, objectInfo, parseObjectInfoResponse } from "./client/upload-pack/object-info.mjs";
+import { V2FetchError, parseV2FetchResponse, v2Fetch, v2FetchObjects } from "./client/upload-pack/fetch.mjs";
 export { LsRefsError, ObjectInfoError, V2CapabilityError, V2FetchError, V2SmartHttpError, createV2HttpTransport, getCommandFeatures, hasCommand, lsRefs, lsRefsToRefAdvertisement, objectInfo, parseLsRefsResponse, parseObjectInfoResponse, parseV2CapabilityAdvertisement, parseV2FetchResponse, v2Fetch, v2FetchObjects };

package/dist/workdir/change-log.mjs

@@ -0,0 +1,63 @@
+//#region src/workdir/change-log.ts
+/**
+* 创建空的变更日志
+*
+* @example
+* ```ts
+* const log = createVirtualChangeLog();
+* log.append({ op: "add", path: "a.txt" });
+* expect(log.toVirtualChanges()).toEqual([{ path: "a.txt", type: "add" }]);
+* ```
+*/
+function createVirtualChangeLog() {
+	const records = [];
+	return {
+		append(record) {
+			records.push(record);
+		},
+		clear() {
+			records.length = 0;
+		},
+		snapshot() {
+			return records.slice();
+		},
+		toVirtualChanges() {
+			const out = [];
+			for (const record of records) {
+				const mapped = mapInternalToVirtual(record);
+				if (mapped !== null) out.push(mapped);
+			}
+			return out;
+		}
+	};
+}
+function mapInternalToVirtual(record) {
+	switch (record.op) {
+		case "add": return {
+			path: record.path,
+			type: "add"
+		};
+		case "modify": return {
+			path: record.path,
+			type: "modify"
+		};
+		case "delete": return {
+			path: record.path,
+			type: "delete"
+		};
+		case "rename": return {
+			path: record.to,
+			type: "rename",
+			oldPath: record.from
+		};
+		case "copy": return {
+			path: record.to,
+			type: "copy",
+			oldPath: record.from
+		};
+		case "revert": return null;
+		default: return record;
+	}
+}
+//#endregion
+export { createVirtualChangeLog };

package/dist/workdir/core.d.mts

@@ -0,0 +1,166 @@
+import { SHA1 } from "../core/types.mjs";
+import { VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError } from "../core/errors.mjs";
+
+//#region src/workdir/core.d.ts
+/**
+ * 虚拟工作目录条目种类
+ *
+ * - `"blob"`: 普通文件或可执行文件（mode 100644 / 100755）
+ * - `"tree"`: 目录（mode 40000）
+ * - `"symlink"`: 符号链接（mode 120000）
+ */
+type VirtualEntryKind = "blob" | "tree" | "symlink";
+/**
+ * 虚拟路径状态信息
+ *
+ * 由 `stat()` 返回，描述路径对应的节点属性。
+ */
+interface VirtualEntryStat {
+  /** 条目种类 */
+  readonly kind: VirtualEntryKind;
+  /** Git 文件模式（如 "100644"、"100755"、"40000"、"120000"） */
+  readonly mode: string;
+  /** 文件大小（对 blob 和 symlink 有效；目录返回 0） */
+  readonly size: number;
+  /** 内容哈希（对 repo-backed 节点返回 origin 哈希；CoW 节点可能为 null） */
+  readonly hash: SHA1 | null;
+}
+/**
+ * 目录条目
+ *
+ * 由 `readdir()` 返回，描述目录下的子条目。
+ */
+interface VirtualDirEntry {
+  /** 条目名称（不含路径前缀） */
+  readonly name: string;
+  /** 条目种类 */
+  readonly kind: VirtualEntryKind;
+  /** Git 文件模式 */
+  readonly mode: string;
+}
+/**
+ * 变更操作类型
+ *
+ * 用于 `listChanges()` 返回的变更记录。
+ */
+type VirtualChangeType = "add" | "modify" | "delete" | "rename" | "copy";
+/**
+ * 单条变更记录
+ *
+ * 由 `listChanges()` 返回，描述 session 内的单次操作。
+ * 变更记录是会话内调试/测试辅助，不保证是最小 diff。
+ */
+interface VirtualChange {
+  /** 操作路径 */
+  readonly path: string;
+  /** 变更操作类型 */
+  readonly type: VirtualChangeType;
+  /** rename/copy 操作的源路径（其他操作为 undefined） */
+  readonly oldPath?: string;
+}
+/**
+ * 创建 VirtualWorkdirSession 的选项
+ */
+interface CreateVirtualWorkdirSessionOptions {
+  /** 基线 tree 的 SHA-1 哈希 */
+  readonly baseTree: SHA1;
+}
+/**
+ * VirtualWorkdirSession（虚拟工作目录会话）
+ *
+ * 提供独立生命周期的可变 tree 视图，基于 `baseTree + CoW overlay` 模型。
+ * 不绑定 commit，不涉及 Git index / 真实工作目录。
+ *
+ * @example
+ * ```ts
+ * import { createMemoryRepository } from "nano-git/repository/memory";
+ * import { createVirtualWorkdirSession } from "nano-git/workdir/memory";
+ *
+ * const repo = createMemoryRepository();
+ * const tree = repo.writeTree(); // 初始空 tree
+ * const session = createVirtualWorkdirSession(repo, { baseTree: tree });
+ *
+ * session.writeFile("hello.txt", Buffer.from("world"));
+ * const newTree = session.writeTree();
+ * ```
+ */
+interface VirtualWorkdirSession {
+  /** 当前基线 tree 的 SHA-1 哈希 */
+  readonly baseTree: SHA1;
+  /** 路径是否存在 */
+  exists(path: string): boolean;
+  /** 获取路径状态信息，不存在时返回 null */
+  stat(path: string): VirtualEntryStat | null;
+  /** 读取目录内容，根目录为 "" */
+  readdir(path?: string): VirtualDirEntry[];
+  /** 读取文件内容 */
+  readFile(path: string): Buffer;
+  /** 读取符号链接目标 */
+  readLink(path: string): string;
+  /** 写入文件（新建或覆盖） */
+  writeFile(path: string, content: Buffer, options?: {
+    readonly mode?: "100644" | "100755";
+  }): void;
+  /** 写入符号链接（新建或覆盖） */
+  writeLink(path: string, target: string): void;
+  /** 创建目录（含必要父目录） */
+  mkdir(path: string): void;
+  /** 删除路径（文件、目录或符号链接） */
+  delete(path: string): void;
+  /**
+   * 重命名路径
+   *
+   * 只做路径重绑定，不退化为 delete + write。
+   * 目录重命名后，子项保持懒加载。
+   */
+  rename(from: string, to: string): void;
+  /**
+   * 复制路径
+   *
+   * 新建 session node，共享 origin，不共享 node 身份。
+   * 目录复制为浅复制，子项保持懒加载。
+   */
+  copy(from: string, to: string): void;
+  /**
+   * 恢复路径到其 origin
+   *
+   * 仅对当前 CoW 节点恢复其 origin（repo-backed 版本）。
+   * 对纯新建节点抛出 VirtualRevertNotSupportedError。
+   */
+  revert(path: string): void;
+  /**
+   * 导出当前 overlay 为新 tree
+   *
+   * 只重新合成受影响目录，复用未修改节点的哈希。
+   * 不自动推进 baseTree。
+   */
+  writeTree(): SHA1;
+  /**
+   * 重置 session 到指定基线 tree
+   *
+   * 丢弃全部 overlay 与变更历史。
+   */
+  reset(baseTree: SHA1): void;
+  /**
+   * 列出会话内的变更记录
+   *
+   * 是会话内调试/测试辅助，不保证是最小 diff 引擎。
+   * 输出稳定、测试可断言即可。
+   */
+  listChanges(): VirtualChange[];
+}
+/**
+ * VirtualWorkdirBackend
+ *
+ * session 内部状态存储的抽象接口。
+ * memory / file / sqlite 后端通过实现此接口来提供不同的持久化策略。
+ *
+ * 本接口在后续 Phase 中会逐步补充完整方法签名。
+ * 当前仅为命名冻结与角色声明。
+ */
+interface VirtualWorkdirBackend {
+  /** 后端类型标识 */
+  readonly kind: "memory" | "file" | "sqlite";
+}
+//#endregion
+export { CreateVirtualWorkdirSessionOptions, VirtualChange, VirtualChangeType, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdirBackend, VirtualWorkdirSession };

package/dist/workdir/core.mjs

@@ -0,0 +1,2 @@
+import { VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError } from "../core/errors.mjs";
+export { VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError };

package/dist/workdir/ids.mjs

@@ -0,0 +1,20 @@
+//#region src/workdir/ids.ts
+/** 根目录节点的固定 ID（每个 session 一致） */
+const VIRTUAL_ROOT_NODE_ID = "root";
+let nextNodeCounter = 1;
+/**
+* 分配新的 session 节点 ID
+*/
+function createNodeId() {
+	const id = `node:${nextNodeCounter}`;
+	nextNodeCounter += 1;
+	return id;
+}
+/**
+* 为仓库对象哈希派生稳定的 session 节点 ID（懒加载、未 copy 前复用）
+*/
+function originBackedNodeId(hash) {
+	return `origin:${hash}`;
+}
+//#endregion
+export { VIRTUAL_ROOT_NODE_ID, createNodeId, originBackedNodeId };

package/dist/workdir/memory-backend.mjs

@@ -0,0 +1,21 @@
+import { VIRTUAL_ROOT_NODE_ID } from "./ids.mjs";
+import { createVirtualChangeLog } from "./change-log.mjs";
+import { createRootDirectoryNode } from "./nodes.mjs";
+//#region src/workdir/memory-backend.ts
+/**
+* Virtual Workdir 会话内存状态（与 ODB 后端无关的纯状态容器）
+*/
+/**
+* 创建初始 session 状态（仅根目录节点，绑定 baseTree origin）
+*/
+function createVirtualWorkdirMemoryState(baseTree) {
+	const nodes = /* @__PURE__ */ new Map();
+	nodes.set(VIRTUAL_ROOT_NODE_ID, createRootDirectoryNode(baseTree));
+	return {
+		baseTree,
+		nodes,
+		changeLog: createVirtualChangeLog()
+	};
+}
+//#endregion
+export { createVirtualWorkdirMemoryState };

package/dist/workdir/memory.d.mts

@@ -0,0 +1,2 @@
+import { createVirtualWorkdirSession } from "./session.mjs";
+export { createVirtualWorkdirSession };

package/dist/workdir/memory.mjs

@@ -0,0 +1,2 @@
+import { createVirtualWorkdirSession } from "./session.mjs";
+export { createVirtualWorkdirSession };

package/dist/workdir/nodes.mjs

@@ -0,0 +1,112 @@
+import { VIRTUAL_ROOT_NODE_ID } from "./ids.mjs";
+import { cloneDirectoryOverlay, createEmptyDirectoryOverlay } from "./overlay.mjs";
+//#region src/workdir/nodes.ts
+/**
+* Virtual Workdir 会话节点状态模型
+*
+* 节点身份（nodeId）与目录路径绑定分离；origin 描述 repo-backed 来源。
+*/
+/**
+* 创建绑定 repo 根 tree 的目录节点（带空 overlay）
+*/
+function createRootDirectoryNode(originTreeHash) {
+	return {
+		id: VIRTUAL_ROOT_NODE_ID,
+		origin: {
+			kind: "repo-tree",
+			hash: originTreeHash
+		},
+		state: {
+			kind: "directory",
+			overlay: createEmptyDirectoryOverlay()
+		}
+	};
+}
+/**
+* 节点是否携带可 revert 的 repo origin
+*/
+function nodeHasRepoOrigin(node) {
+	return node.origin.kind === "repo-tree" || node.origin.kind === "repo-blob";
+}
+/**
+* 目录 overlay 是否有 session 层修改
+*/
+function isDirectoryOverlayDirty(overlay) {
+	return overlay.addedEntries.size > 0 || overlay.deletedNames.size > 0;
+}
+/**
+* 将节点状态恢复到 origin 语义（丢弃 materialize / 目录 overlay）
+*
+* 无 repo origin 时返回原状态引用，由上层决定是否抛错。
+*/
+function revertNodeState(node) {
+	if (!nodeHasRepoOrigin(node)) return node;
+	if (node.state.kind === "directory") return {
+		...node,
+		state: {
+			kind: "directory",
+			overlay: createEmptyDirectoryOverlay()
+		}
+	};
+	if (node.state.kind === "file") {
+		const mode = node.state.mode;
+		return {
+			...node,
+			state: {
+				kind: "file",
+				mode
+			}
+		};
+	}
+	return {
+		...node,
+		state: {
+			kind: "symlink",
+			mode: "120000"
+		}
+	};
+}
+/**
+* 为 `copy` 创建新节点：共享 origin，目录为浅复制（子项绑定保留，但 nodeId 为新）
+*/
+function cloneSessionNodeForCopy(source, newId) {
+	const origin = source.origin;
+	if (source.state.kind === "directory") return {
+		id: newId,
+		origin,
+		state: {
+			kind: "directory",
+			overlay: cloneDirectoryOverlay(source.state.overlay)
+		}
+	};
+	if (source.state.kind === "file") {
+		const content = source.state.content;
+		return {
+			id: newId,
+			origin,
+			state: content === void 0 ? {
+				kind: "file",
+				mode: source.state.mode
+			} : {
+				kind: "file",
+				mode: source.state.mode,
+				content: Buffer.from(content)
+			}
+		};
+	}
+	const target = source.state.target;
+	return {
+		id: newId,
+		origin,
+		state: target === void 0 ? {
+			kind: "symlink",
+			mode: "120000"
+		} : {
+			kind: "symlink",
+			mode: "120000",
+			target: Buffer.from(target)
+		}
+	};
+}
+//#endregion
+export { cloneSessionNodeForCopy, createRootDirectoryNode, isDirectoryOverlayDirty, revertNodeState };