nano-git 0.3.1 → 0.3.3

package/README.md

@@ -381,7 +381,7 @@ Git 使用内容寻址文件系统，所有对象通过 SHA-1 哈希寻址：
 
 存储目录内容，每个条目包含：
 
-- 文件模式（如 `100644` 普通文件，`100755` 可执行文件，`040000` 目录）
+- 文件模式（如 `100644` 普通文件，`100755` 可执行文件，`040000` 目录，API 中均使用规范 6 位形式）
 - 文件名
 - 指向 blob 或子 tree 的哈希
 

package/dist/core/types.d.mts

@@ -48,7 +48,7 @@ interface GitBlob {
 }
 /** Tree 条目 — 目录中的一个文件或子目录 */
 interface TreeEntry {
-  /** 文件模式（如 "100644" 普通文件, "100755" 可执行文件, "40000" 目录） */
+  /** 文件模式（如 "100644" 普通文件, "100755" 可执行文件, "040000" 目录） */
   mode: string;
   /** 文件/目录名 */
   name: string;

package/dist/objects/tree.d.mts

@@ -4,6 +4,8 @@ import { GitTree } from "../core/types.mjs";
 /**
  * 序列化 Tree 对象
  *
+ * 写入时自动将规范 mode 转换为磁盘格式（如 "040000" → "40000"）。
+ *
  * @example
  * ```ts
  * const tree: GitTree = {
@@ -16,6 +18,8 @@ import { GitTree } from "../core/types.mjs";
 declare function serializeTree(tree: GitTree): Buffer;
 /**
  * 反序列化 Tree 对象
+ *
+ * 读取时自动将磁盘 mode 转换为规范形式（如 "40000" → "040000"）。
  */
 declare function deserializeTree(content: Buffer): GitTree;
 //#endregion

package/dist/objects/tree.mjs

@@ -9,10 +9,58 @@ import { sha1 } from "../core/types.mjs";
 * - mode: 文件模式（如 "100644"）
 * - name: 文件名
 * - hash: 20 字节的原始 SHA-1（不是十六进制字符串）
+*
+* mode 规范化说明：
+* Git CLI 显示目录 mode 为 "040000"（6 位八进制，前导补零），但磁盘上存储为 "40000"（5 字节）。
+* 本模块在序列化/反序列化边界做双向转换，内部统一使用规范形式（"040000"）。
+*/
+/**
+* 目录 mode 的磁盘格式（无前导零，5 字节）
 */
+const DIR_MODE_ON_DISK = "40000";
+/**
+* 目录 mode 的规范格式（有前导零，6 字节，与 git cat-file -p 显示一致）
+*/
+const DIR_MODE_CANONICAL = "040000";
+/**
+* 将 mode 转换为规范形式（6 位八进制）
+*
+* 读取磁盘 tree 条目时调用：将 "40000" → "040000"，其他 mode 不变。
+*
+* @param mode - 来自磁盘的 mode 字符串
+* @returns 规范化的 mode 字符串
+*
+* @example
+* ```ts
+* toCanonicalMode("40000")  // => "040000"
+* toCanonicalMode("100644") // => "100644"
+* ```
+*/
+function toCanonicalMode(mode) {
+	return mode === DIR_MODE_ON_DISK ? DIR_MODE_CANONICAL : mode;
+}
+/**
+* 将 mode 转换为磁盘格式（无多余前导零）
+*
+* 写入磁盘 tree 条目时调用：将 "040000" → "40000"，其他 mode 不变。
+*
+* @param mode - 规范形式的 mode 字符串
+* @returns 磁盘形式的 mode 字符串
+*
+* @example
+* ```ts
+* toOnDiskMode("040000") // => "40000"
+* toOnDiskMode("100644") // => "100644"
+* ```
+*/
+function toOnDiskMode(mode) {
+	return mode === DIR_MODE_CANONICAL ? DIR_MODE_ON_DISK : mode;
+}
 /**
 * 序列化 Tree 对象
 *
+* 写入时自动将规范 mode 转换为磁盘格式（如 "040000" → "40000"）。
+*
 * @example
 * ```ts
 * const tree: GitTree = {
@@ -25,7 +73,8 @@ import { sha1 } from "../core/types.mjs";
 function serializeTree(tree) {
 	const buffers = [];
 	for (const entry of tree.entries) {
-		const entryHeader = Buffer.from(`${entry.mode} ${entry.name}\0`, "utf-8");
+		const mode = toOnDiskMode(entry.mode);
+		const entryHeader = Buffer.from(`${mode} ${entry.name}\0`, "utf-8");
 		const entryHash = Buffer.from(entry.hash, "hex");
 		if (entryHash.length !== 20) throw new InvalidObjectError(`invalid SHA-1 hash length: ${entryHash.length}`);
 		buffers.push(entryHeader, entryHash);
@@ -34,6 +83,8 @@ function serializeTree(tree) {
 }
 /**
 * 反序列化 Tree 对象
+*
+* 读取时自动将磁盘 mode 转换为规范形式（如 "40000" → "040000"）。
 */
 function deserializeTree(content) {
 	const entries = [];
@@ -51,7 +102,7 @@ function deserializeTree(content) {
 		if (hashEnd > content.length) throw new InvalidObjectError("tree: truncated hash");
 		const hash = content.subarray(hashStart, hashEnd).toString("hex");
 		entries.push({
-			mode,
+			mode: toCanonicalMode(mode),
 			name,
 			hash: sha1(hash)
 		});

package/dist/repository/tree/tree-patch.mjs

@@ -98,7 +98,7 @@ function processOpsSequentially(objects, rootHash, ops) {
 * 在 tree 中查找路径对应的条目
 *
 * 沿路径依次读取 tree 对象，最后一段返回目标条目。
-* 中间段必须为目录（mode "40000"），否则抛出异常。
+* 中间段必须为目录（mode "040000"），否则抛出异常。
 */
 function findEntryByPath(objects, treeHash, path) {
 	const segments = path.split("/");
@@ -109,7 +109,7 @@ function findEntryByPath(objects, treeHash, path) {
 		const entry = obj.entries.find((e) => e.name === segments[i]);
 		if (!entry) return null;
 		if (i === segments.length - 1) return entry;
-		if (entry.mode !== "40000") throw new Error(`Cannot access '${segments.slice(0, i + 1).join("/")}': not a directory (mode: ${entry.mode})`);
+		if (entry.mode !== "040000") throw new Error(`Cannot access '${segments.slice(0, i + 1).join("/")}': not a directory (mode: ${entry.mode})`);
 		currentHash = entry.hash;
 	}
 	return null;
@@ -174,7 +174,7 @@ function applyPatchRecursive(objects, treeHash, ops, prefix, upsertedPaths) {
 	for (const [name, childOps] of deeperOps) {
 		const existingEntry = existingEntries.find((e) => e.name === name);
 		const existingHash = existingEntry?.hash ?? null;
-		if (existingEntry !== void 0 && existingEntry.mode !== "40000") throw new Error(`Cannot access '${prefix}${name}': existing entry is not a directory (mode: ${existingEntry.mode})`);
+		if (existingEntry !== void 0 && existingEntry.mode !== "040000") throw new Error(`Cannot access '${prefix}${name}': existing entry is not a directory (mode: ${existingEntry.mode})`);
 		if (existingHash === null) {
 			const hasUpsertInBatch = childOps.some((op) => op.op === "upsert") || childOps.some((op) => op.op === "delete" && upsertedPaths.has(`${prefix}${name}/${op.path}`));
 			if (childOps.every((op) => op.op === "delete") && !hasUpsertInBatch) {
@@ -185,7 +185,7 @@ function applyPatchRecursive(objects, treeHash, ops, prefix, upsertedPaths) {
 		const result = applyPatchRecursive(objects, existingHash, childOps, `${prefix}${name}/`, upsertedPaths);
 		writtenTrees.push(...result.written);
 		finalEntryMap.set(name, {
-			mode: "40000",
+			mode: "040000",
 			name,
 			hash: result.hash
 		});

package/dist/repository/tree/tree-walk.mjs

@@ -58,7 +58,7 @@ function walkTreeRecursive(objects, treeHash, prefix, result, visit) {
 		};
 		if (result) result.push(entryWithPath);
 		if (visit) visit(entryWithPath);
-		if (entry.mode === "40000") walkTreeRecursive(objects, entry.hash, path, result, visit);
+		if (entry.mode === "040000") walkTreeRecursive(objects, entry.hash, path, result, visit);
 	}
 }
 //#endregion

package/dist/repository/tree/tree-writer.mjs

@@ -31,7 +31,7 @@ function writeTreeRecursive(store, dirPath) {
 		if (stat.isDirectory()) {
 			const subtreeHash = writeTreeRecursive(store, fullPath);
 			entries.push({
-				mode: "40000",
+				mode: "040000",
 				name,
 				hash: subtreeHash
 			});

package/dist/workdir/change-index-plan.mjs

@@ -1,9 +1,9 @@
-import { resolvePath } from "./session-internal.mjs";
+import { resolvePath } from "./workdir-path.mjs";
 //#region src/workdir/change-index-plan.ts
 /**
 * Virtual Workdir change-index 刷新策略
 *
-* 把 session 写路径里的“是否允许增量刷新”判断与
+* 把 workdir 写路径里的“是否允许增量刷新”判断与
 * “应该执行哪种 change-index 更新动作”集中到单独模块。
 */
 /**

package/dist/workdir/change-index.mjs

@@ -1,6 +1,6 @@
 import { hashObject } from "../core/hash-digest.mjs";
 import { readRepoBlobContent, readRepoTree } from "./origin.mjs";
-import { getDirectoryChildrenView, joinChildPath, resolveCurrentLeafAtPath } from "./session-internal.mjs";
+import { getDirectoryChildrenView, joinChildPath, resolveCurrentLeafAtPath } from "./workdir-path.mjs";
 import { observeListedDirectoryChild } from "./directory-view.mjs";
 //#region src/workdir/change-index.ts
 /**
@@ -15,7 +15,7 @@ import { observeListedDirectoryChild } from "./directory-view.mjs";
 */
 const baseSnapshotCache = /* @__PURE__ */ new WeakMap();
 /**
-* 重建当前 session 的规范化变更索引。
+* 重建当前 workdir 的规范化变更索引。
 *
 * @example
 * ```ts
@@ -173,7 +173,7 @@ function rewriteChangeRecordForRename(source, state, from, to, cache) {
 * 为 copy 目标路径写入折叠后的变更记录。
 *
 * 仅适用于叶子节点 copy；
-* session-only 来源允许退化为普通 create。
+* workdir-only 来源允许退化为普通 create。
 */
 function writeChangeRecordForCopy(source, state, from, to, cache) {
 	const sourceRecord = state.getChangeRecord(from);
@@ -195,7 +195,7 @@ function snapshotBaseTree(source, treeHash, dirPath) {
 	const out = [];
 	for (const entry of tree.entries) {
 		const path = joinChildPath(dirPath, entry.name);
-		if (entry.mode === "40000") {
+		if (entry.mode === "040000") {
 			out.push(...snapshotBaseTree(source, entry.hash, path));
 			continue;
 		}
@@ -218,7 +218,7 @@ function baseSnapshotViewForTree(source, treeHash) {
 }
 function snapshotCurrentTree(source, state, cache) {
 	const root = state.getNode("root");
-	if (root === null) throw new Error("Virtual workdir session is missing root node");
+	if (root === null) throw new Error("Virtual workdir is missing root node");
 	return snapshotCurrentNode(source, state, root, "", cache);
 }
 function snapshotCurrentNode(source, state, node, path, cache) {
@@ -398,7 +398,7 @@ function modeKind(mode) {
 	return mode === "120000" ? "symlink" : "blob";
 }
 /**
-* 从规范化变更索引导出当前 session 的最终 diff。
+* 从规范化变更索引导出当前 workdir 的最终 diff。
 *
 * @example
 * ```ts

package/dist/workdir/core.d.mts

@@ -1,5 +1,4 @@
 import { SHA1 } from "../core/types.mjs";
-import { ObjectDatabase } from "../core/types/odb.mjs";
 import { VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError } from "../core/errors.mjs";
 
 //#region src/workdir/core.d.ts
@@ -19,7 +18,7 @@ type VirtualEntryKind = "blob" | "tree" | "symlink";
 interface VirtualEntryStat {
   /** 条目种类 */
   readonly kind: VirtualEntryKind;
-  /** Git 文件模式（如 "100644"、"100755"、"40000"、"120000"） */
+  /** Git 文件模式（如 "100644"、"100755"、"040000"、"120000"） */
   readonly mode: string;
   /** 文件大小（对 blob 和 symlink 有效；目录返回 0） */
   readonly size: number;
@@ -93,42 +92,36 @@ type VirtualDiffEntry = {
   readonly source?: VirtualDiffSource;
 };
 /**
- * 创建 VirtualWorkdirSession 的选项
+ * 创建 VirtualWorkdir 的选项
  */
-interface CreateVirtualWorkdirSessionOptions {
+interface CreateVirtualWorkdirOptions {
   /** 基线 tree 的 SHA-1 哈希 */
   readonly baseTree: SHA1;
 }
 /**
- * Virtual Workdir session 标识
- */
-type VirtualWorkdirSessionId = string & {
-  readonly __brand: "VirtualWorkdirSessionId";
-};
-/**
- * VirtualWorkdirSession（虚拟工作目录会话）
+ * VirtualWorkdir（虚拟工作目录实例）
  *
  * 提供独立生命周期的可变 tree 视图，基于 `baseTree + CoW overlay` 模型。
  * 不绑定 commit，不涉及 Git index / 真实工作目录。
  *
- * 当前 session 对 origin 仓库对象采用弱保证：
+ * 当前实例对 origin 仓库对象采用弱保证：
  * 如果 base tree / origin blob 在后续被移除、损坏或不可读取，
  * 相关读取、`revert()`、`writeTree()` 等操作会抛出 `VirtualOriginUnavailableError`。
  *
  * @example
  * ```ts
  * import { createMemoryRepository } from "nano-git/repository/memory";
- * import { createVirtualWorkdirSession } from "nano-git/workdir/memory";
+ * import { createVirtualWorkdir } from "nano-git/workdir/memory";
  *
  * const repo = createMemoryRepository();
  * const tree = repo.writeTree(); // 初始空 tree
- * const session = createVirtualWorkdirSession(repo, { baseTree: tree });
+ * const workdir = createVirtualWorkdir(repo.objects, { baseTree: tree });
  *
- * session.writeFile("hello.txt", Buffer.from("world"));
- * const newTree = session.writeTree();
+ * workdir.writeFile("hello.txt", Buffer.from("world"));
+ * const newTree = workdir.writeTree();
  * ```
  */
-interface VirtualWorkdirSession {
+interface VirtualWorkdir {
   /** 当前基线 tree 的 SHA-1 哈希 */
   readonly baseTree: SHA1;
   /** 路径是否存在 */
@@ -161,7 +154,7 @@ interface VirtualWorkdirSession {
   /**
    * 复制路径
    *
-   * 新建 session node，共享 origin，不共享 node 身份。
+   * 新建 workdir node，共享 origin，不共享 node 身份。
    * 目录复制为浅复制，子项保持懒加载。
    */
   copy(from: string, to: string): void;
@@ -186,35 +179,11 @@ interface VirtualWorkdirSession {
    */
   writeTree(): SHA1;
   /**
-   * 重置 session 到指定基线 tree
+   * 重置当前实例到指定基线 tree
    *
    * 丢弃全部 overlay 与变更历史。
    */
   reset(baseTree: SHA1): void;
 }
-/**
- * VirtualWorkdirBackend
- *
- * session 内部状态存储的抽象接口。
- * memory / file / sqlite 后端通过实现此接口来提供不同的持久化策略。
- *
- * `file` / `sqlite` 持久化 backend 当前都按单进程、单写者场景收口；
- * 不承诺跨进程并发写安全，也不提供多写者协调协议。
- *
- * 本接口在后续 Phase 中会逐步补充完整方法签名。
- * 当前仅为命名冻结与角色声明。
- */
-interface VirtualWorkdirBackend {
-  /** 后端类型标识 */
-  readonly kind: "memory" | "file" | "sqlite";
-  /** 创建新 session 并返回其标识 */
-  createSession(options: CreateVirtualWorkdirSessionOptions): VirtualWorkdirSessionId;
-  /** 打开已存在的 session */
-  openSession(source: ObjectDatabase, sessionId: VirtualWorkdirSessionId): VirtualWorkdirSession;
-  /** 删除 session */
-  deleteSession(sessionId: VirtualWorkdirSessionId): void;
-  /** 列出当前后端中可完整恢复的 session */
-  listSessions(): VirtualWorkdirSessionId[];
-}
 //#endregion
-export { CreateVirtualWorkdirSessionOptions, VirtualDiffChanges, VirtualDiffEntry, VirtualDiffObject, VirtualDiffSource, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdirBackend, VirtualWorkdirSession, VirtualWorkdirSessionId };
+export { CreateVirtualWorkdirOptions, VirtualDiffChanges, VirtualDiffEntry, VirtualDiffObject, VirtualDiffSource, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdir };

package/dist/workdir/directory-view.mjs

@@ -1,10 +1,10 @@
 import { VirtualNotDirectoryError } from "../core/errors.mjs";
-import { ensureNodeFromTreeEntry, joinChildPath, listDirectoryChildren } from "./session-internal.mjs";
+import { ensureNodeFromTreeEntry, joinChildPath, listDirectoryChildren } from "./workdir-path.mjs";
 //#region src/workdir/directory-view.ts
 /**
 * Virtual Workdir 目录展开、观察与编译计划
 *
-* 从 session-internal.ts 拆分，聚焦以下职责：
+* 从 workdir-path.ts 拆分，聚焦以下职责：
 * - 目录子项观察（observeDirectoryChildren / observeListedDirectoryChild / observeNamedDirectoryChild）
 * - origin 按名查询视图（createNamedOriginChildLookup）
 * - 受影响子项编译计划（planAffectedDirectoryChildren）

package/dist/workdir/dirty-dir-plan.mjs

@@ -1,12 +1,12 @@
-import { getRootNode } from "./session-internal.mjs";
+import { getRootNode } from "./workdir-path.mjs";
 import { observeDirectoryChildren } from "./directory-view.mjs";
 import { createDirtyDirSummary } from "./dirty-dir.mjs";
 //#region src/workdir/dirty-dir-plan.ts
 /**
 * Virtual Workdir dirty-dir summary 重建策略
 *
-* 把 session 写路径里的脏目录摘要清理与重建逻辑集中到单独模块，
-* 让 session.ts 更接近纯编排层。
+* 把 workdir 写路径里的脏目录摘要清理与重建逻辑集中到单独模块，
+* 让 workdir.ts 更接近纯编排层。
 */
 /**
 * 创建 dirty-dir summary 策略器。

package/dist/workdir/file-backend.d.mts

@@ -1,22 +1,44 @@
-import { VirtualWorkdirBackend } from "./core.mjs";
+import { ObjectDatabase } from "../core/types/odb.mjs";
+import { CreateVirtualWorkdirOptions, VirtualWorkdir } from "./core.mjs";
+import { VirtualWorkdirStateStore } from "./state-store.mjs";
 
 //#region src/workdir/file-backend.d.ts
-/** 创建文件系统 Virtual Workdir backend 的可选参数 */
-interface CreateFileVirtualWorkdirBackendOptions {
-  /** session 根目录名，默认 `sessions` */
-  readonly sessionsDirName?: string;
+/** 打开文件系统 VirtualWorkdir 的可选参数 */
+interface OpenFileVirtualWorkdirOptions extends CreateVirtualWorkdirOptions {
+  /** 不存在时按 baseTree 初始化 */
+  readonly create?: boolean;
 }
 /**
- * 创建基于文件系统目录的 Virtual Workdir backend
+ * 打开基于目录持久化的 VirtualWorkdir
  *
  * @example
  * ```ts
- * const backend = createFileVirtualWorkdirBackend("/tmp/workdirs");
- * const sessionId = backend.createSession({ baseTree: tree });
- * const session = backend.openSession(repo.objects, sessionId);
- * expect(session.baseTree).toBe(tree);
+ * const workdir = openFileVirtualWorkdir(repo.objects, "/tmp/workdir", {
+ *   baseTree: tree,
+ *   create: true,
+ * });
+ * expect(workdir.baseTree).toBe(tree);
  * ```
  */
-declare function createFileVirtualWorkdirBackend(rootDir: string, options?: CreateFileVirtualWorkdirBackendOptions): VirtualWorkdirBackend;
+declare function openFileVirtualWorkdir(source: ObjectDatabase, workdirDir: string, options: OpenFileVirtualWorkdirOptions): VirtualWorkdir;
+/**
+ * 删除指定目录上的持久化 VirtualWorkdir
+ *
+ * @example
+ * ```ts
+ * deleteFileVirtualWorkdir("/tmp/workdir");
+ * ```
+ */
+declare function deleteFileVirtualWorkdir(workdirDir: string): void;
+/**
+ * 创建单个文件系统 VirtualWorkdir 的状态存储
+ *
+ * @example
+ * ```ts
+ * const store = createFileVirtualWorkdirStateStore("/tmp/workdir");
+ * expect(store.kind).toBe("file");
+ * ```
+ */
+declare function createFileVirtualWorkdirStateStore(workdirDir: string): VirtualWorkdirStateStore;
 //#endregion
-export { CreateFileVirtualWorkdirBackendOptions, createFileVirtualWorkdirBackend };
+export { OpenFileVirtualWorkdirOptions, createFileVirtualWorkdirStateStore, deleteFileVirtualWorkdir, openFileVirtualWorkdir };