nano-git 0.2.1 → 0.2.3

package/dist/workdir/change-log.d.mts

@@ -0,0 +1,25 @@
+//#region src/workdir/change-log.d.ts
+/** 内部变更操作（含 revert，公开 API 暂不暴露 revert） */
+type InternalChangeRecord = {
+  readonly op: "add";
+  readonly path: string;
+} | {
+  readonly op: "modify";
+  readonly path: string;
+} | {
+  readonly op: "delete";
+  readonly path: string;
+} | {
+  readonly op: "rename";
+  readonly from: string;
+  readonly to: string;
+} | {
+  readonly op: "copy";
+  readonly from: string;
+  readonly to: string;
+} | {
+  readonly op: "revert";
+  readonly path: string;
+};
+//#endregion
+export { InternalChangeRecord };

package/dist/workdir/change-log.mjs

@@ -22,15 +22,21 @@ function createVirtualChangeLog() {
 			return records.slice();
 		},
 		toVirtualChanges() {
-			const out = [];
-			for (const record of records) {
-				const mapped = mapInternalToVirtual(record);
-				if (mapped !== null) out.push(mapped);
-			}
-			return out;
+			return mapInternalChangesToVirtualChanges(records);
 		}
 	};
 }
+/**
+* 将内部变更记录映射为公开 VirtualChange 列表
+*/
+function mapInternalChangesToVirtualChanges(records) {
+	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 {
@@ -60,4 +66,4 @@ function mapInternalToVirtual(record) {
 	}
 }
 //#endregion
-export { createVirtualChangeLog };
+export { createVirtualChangeLog, mapInternalChangesToVirtualChanges };

package/dist/workdir/core.d.mts

@@ -1,4 +1,5 @@
 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
@@ -65,12 +66,22 @@ interface CreateVirtualWorkdirSessionOptions {
   /** 基线 tree 的 SHA-1 哈希 */
   readonly baseTree: SHA1;
 }
+/**
+ * Virtual Workdir session 标识
+ */
+type VirtualWorkdirSessionId = string & {
+  readonly __brand: "VirtualWorkdirSessionId";
+};
 /**
  * VirtualWorkdirSession（虚拟工作目录会话）
  *
  * 提供独立生命周期的可变 tree 视图，基于 `baseTree + CoW overlay` 模型。
  * 不绑定 commit，不涉及 Git index / 真实工作目录。
  *
+ * 当前 session 对 origin 仓库对象采用弱保证：
+ * 如果 base tree / origin blob 在后续被移除、损坏或不可读取，
+ * 相关读取、`revert()`、`writeTree()` 等操作会抛出 `VirtualOriginUnavailableError`。
+ *
  * @example
  * ```ts
  * import { createMemoryRepository } from "nano-git/repository/memory";
@@ -155,12 +166,23 @@ interface VirtualWorkdirSession {
  * 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, VirtualChange, VirtualChangeType, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdirBackend, VirtualWorkdirSession };
+export { CreateVirtualWorkdirSessionOptions, VirtualChange, VirtualChangeType, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdirBackend, VirtualWorkdirSession, VirtualWorkdirSessionId };

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

@@ -0,0 +1,22 @@
+import { VirtualWorkdirBackend } from "./core.mjs";
+
+//#region src/workdir/file-backend.d.ts
+/** 创建文件系统 Virtual Workdir backend 的可选参数 */
+interface CreateFileVirtualWorkdirBackendOptions {
+  /** session 根目录名，默认 `sessions` */
+  readonly sessionsDirName?: string;
+}
+/**
+ * 创建基于文件系统目录的 Virtual Workdir backend
+ *
+ * @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);
+ * ```
+ */
+declare function createFileVirtualWorkdirBackend(rootDir: string, options?: CreateFileVirtualWorkdirBackendOptions): VirtualWorkdirBackend;
+//#endregion
+export { CreateFileVirtualWorkdirBackendOptions, createFileVirtualWorkdirBackend };

package/dist/workdir/file-backend.mjs

@@ -0,0 +1,366 @@
+import { createRootDirectoryNode } from "./nodes.mjs";
+import { createVirtualWorkdirSessionId } from "./session-id.mjs";
+import { openVirtualWorkdirSession } from "./session.mjs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+//#region src/workdir/file-backend.ts
+/**
+* Virtual Workdir 文件系统 backend
+*/
+const FILE_WORKDIR_MANIFEST_VERSION = 1;
+const FILE_WORKDIR_TRANSACTION_SNAPSHOT_SUFFIX = ".txn-snapshot";
+/**
+* 创建基于文件系统目录的 Virtual Workdir backend
+*
+* @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);
+* ```
+*/
+function createFileVirtualWorkdirBackend(rootDir, options = {}) {
+	const sessionsRoot = join(rootDir, options.sessionsDirName ?? "sessions");
+	mkdirSync(sessionsRoot, { recursive: true });
+	return {
+		kind: "file",
+		createSession(options) {
+			const sessionId = createVirtualWorkdirSessionId();
+			createFileVirtualWorkdirStateStore(sessionsRoot, sessionId).reset(options.baseTree);
+			return sessionId;
+		},
+		openSession(source, sessionId) {
+			if (!hasSession(sessionsRoot, sessionId)) throw new Error(`Virtual workdir session not found: ${sessionId}`);
+			validateSessionIntegrity(sessionsRoot, sessionId);
+			return openVirtualWorkdirSession(source, createFileVirtualWorkdirStateStore(sessionsRoot, sessionId));
+		},
+		deleteSession(sessionId) {
+			if (!hasSession(sessionsRoot, sessionId)) throw new Error(`Virtual workdir session not found: ${sessionId}`);
+			rmSync(getSessionDir(sessionsRoot, sessionId), {
+				recursive: true,
+				force: true
+			});
+		},
+		listSessions() {
+			if (!existsSync(sessionsRoot)) return [];
+			return readdirSync(sessionsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => !entry.name.endsWith(FILE_WORKDIR_TRANSACTION_SNAPSHOT_SUFFIX)).filter((entry) => existsSync(getManifestPath(join(sessionsRoot, entry.name)))).map((entry) => decodePathToken(entry.name)).filter((sessionId) => {
+				try {
+					validateSessionIntegrity(sessionsRoot, sessionId);
+					return true;
+				} catch {
+					return false;
+				}
+			}).sort();
+		}
+	};
+}
+/**
+* 创建单个 session 的文件系统状态存储
+*
+* @example
+* ```ts
+* const store = createFileVirtualWorkdirStateStore("/tmp/workdirs/sessions", sessionId);
+* expect(store.kind).toBe("file");
+* ```
+*/
+function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
+	const sessionDir = getSessionDir(sessionsRoot, sessionId);
+	const manifestPath = getManifestPath(sessionDir);
+	const contentDir = getContentDir(sessionDir);
+	return {
+		kind: "file",
+		transact(fn) {
+			const snapshotDir = `${sessionDir}${FILE_WORKDIR_TRANSACTION_SNAPSHOT_SUFFIX}`;
+			rmSync(snapshotDir, {
+				recursive: true,
+				force: true
+			});
+			if (existsSync(sessionDir)) copyDirectoryRecursive(sessionDir, snapshotDir);
+			try {
+				const result = fn();
+				rmSync(snapshotDir, {
+					recursive: true,
+					force: true
+				});
+				return result;
+			} catch (error) {
+				rmSync(sessionDir, {
+					recursive: true,
+					force: true
+				});
+				if (existsSync(snapshotDir)) renameSync(snapshotDir, sessionDir);
+				throw error;
+			}
+		},
+		readBaseTree() {
+			return readManifest(manifestPath).baseTree;
+		},
+		writeBaseTree(baseTree) {
+			updateManifest(sessionDir, (manifest) => ({
+				...manifest,
+				baseTree
+			}));
+		},
+		getNode(id) {
+			const record = readManifest(manifestPath).nodes[id];
+			if (record === void 0) return null;
+			return restoreNode(record, contentDir);
+		},
+		setNode(node) {
+			updateManifest(sessionDir, (manifest) => {
+				const record = persistNode(contentDir, node);
+				return {
+					...manifest,
+					nodes: {
+						...manifest.nodes,
+						[node.id]: record
+					}
+				};
+			});
+		},
+		deleteNode(id) {
+			updateManifest(sessionDir, (manifest) => {
+				if (manifest.nodes[id] === void 0) return manifest;
+				const { [id]: _deleted, ...rest } = manifest.nodes;
+				return {
+					...manifest,
+					nodes: rest
+				};
+			});
+		},
+		appendChange(record) {
+			updateManifest(sessionDir, (manifest) => ({
+				...manifest,
+				changes: [...manifest.changes, record]
+			}));
+		},
+		listChangeRecords() {
+			return readManifest(manifestPath).changes;
+		},
+		clearChanges() {
+			updateManifest(sessionDir, (manifest) => ({
+				...manifest,
+				changes: []
+			}));
+		},
+		reset(baseTree) {
+			rmSync(sessionDir, {
+				recursive: true,
+				force: true
+			});
+			ensureSessionDirs(sessionDir, contentDir);
+			writeManifestAtomic(manifestPath, createManifest(baseTree, { [createRootDirectoryNode(baseTree).id]: serializeDirectoryNode(createRootDirectoryNode(baseTree)) }));
+		}
+	};
+}
+function hasSession(sessionsRoot, sessionId) {
+	return existsSync(getManifestPath(getSessionDir(sessionsRoot, sessionId)));
+}
+function validateSessionIntegrity(sessionsRoot, sessionId) {
+	const sessionDir = getSessionDir(sessionsRoot, sessionId);
+	const manifest = readManifest(getManifestPath(sessionDir));
+	const root = manifest.nodes.root;
+	if (root === void 0) throw new Error(`Virtual workdir session is corrupted: missing root node for ${sessionId}`);
+	if (restoreNode(root, getContentDir(sessionDir)).state.kind !== "directory") throw new Error(`Virtual workdir session is corrupted: root node is not a directory for ${sessionId}`);
+	for (const record of Object.values(manifest.nodes)) restoreNode(record, getContentDir(sessionDir));
+}
+function getSessionDir(sessionsRoot, sessionId) {
+	return join(sessionsRoot, encodePathToken(sessionId));
+}
+function getManifestPath(sessionDir) {
+	return join(sessionDir, "manifest.json");
+}
+function getContentDir(sessionDir) {
+	return join(sessionDir, "content");
+}
+function getContentPath(contentDir, payloadRef) {
+	return join(contentDir, `${encodePathToken(payloadRef)}.bin`);
+}
+function ensureSessionDirs(sessionDir, contentDir) {
+	mkdirSync(sessionDir, { recursive: true });
+	mkdirSync(contentDir, { recursive: true });
+}
+function copyDirectoryRecursive(sourceDir, targetDir) {
+	mkdirSync(targetDir, { recursive: true });
+	for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+		const sourcePath = join(sourceDir, entry.name);
+		const targetPath = join(targetDir, entry.name);
+		if (entry.isDirectory()) {
+			copyDirectoryRecursive(sourcePath, targetPath);
+			continue;
+		}
+		writeFileSync(targetPath, readFileSync(sourcePath));
+	}
+}
+function createManifest(baseTree, nodes) {
+	return {
+		formatVersion: FILE_WORKDIR_MANIFEST_VERSION,
+		baseTree,
+		changes: [],
+		nodes
+	};
+}
+function updateManifest(sessionDir, updater) {
+	const manifestPath = getManifestPath(sessionDir);
+	ensureSessionDirs(sessionDir, getContentDir(sessionDir));
+	writeManifestAtomic(manifestPath, updater(readManifest(manifestPath)));
+}
+function writeManifestAtomic(path, manifest) {
+	writeJsonAtomic(path, manifest);
+}
+function readManifest(manifestPath) {
+	if (!existsSync(manifestPath)) throw new Error(`Virtual workdir session manifest not found: ${manifestPath}`);
+	const manifest = readJson(manifestPath);
+	validateManifest(manifest);
+	return manifest;
+}
+function validateManifest(manifest) {
+	if (typeof manifest.baseTree !== "string" || manifest.baseTree.length === 0) throw new Error("Invalid virtual workdir manifest baseTree");
+	if (!Array.isArray(manifest.changes)) throw new Error("Invalid virtual workdir manifest changes");
+	if (typeof manifest.nodes !== "object" || manifest.nodes === null || Array.isArray(manifest.nodes)) throw new Error("Invalid virtual workdir manifest nodes");
+	if (manifest.formatVersion !== FILE_WORKDIR_MANIFEST_VERSION) throw new Error(`Unsupported virtual workdir file manifest version: expected ${FILE_WORKDIR_MANIFEST_VERSION}, got ${manifest.formatVersion}`);
+}
+function persistNode(contentDir, node) {
+	if (node.state.kind === "directory") return serializeDirectoryNode(node);
+	if (node.state.kind === "file") {
+		const contentRef = node.state.content === void 0 ? null : persistPayload(contentDir, node.id, node.state.content);
+		return {
+			id: node.id,
+			origin: node.origin,
+			state: {
+				kind: "file",
+				mode: node.state.mode,
+				contentRef
+			}
+		};
+	}
+	const targetRef = node.state.target === void 0 ? null : persistPayload(contentDir, node.id, node.state.target);
+	return {
+		id: node.id,
+		origin: node.origin,
+		state: {
+			kind: "symlink",
+			mode: "120000",
+			targetRef
+		}
+	};
+}
+function serializeDirectoryNode(node) {
+	if (node.state.kind !== "directory") throw new Error("serializeDirectoryNode: node is not a directory");
+	return {
+		id: node.id,
+		origin: node.origin,
+		state: {
+			kind: "directory",
+			overlay: {
+				addedEntries: Array.from(node.state.overlay.addedEntries.entries()),
+				deletedNames: Array.from(node.state.overlay.deletedNames.values())
+			}
+		}
+	};
+}
+function persistPayload(contentDir, nodeId, payload) {
+	mkdirSync(contentDir, { recursive: true });
+	const payloadRef = `${nodeId}:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`;
+	writeBufferAtomic(getContentPath(contentDir, payloadRef), payload);
+	return payloadRef;
+}
+function restoreNode(record, contentDir) {
+	const origin = restoreOrigin(record.origin);
+	if (record.state.kind === "directory") return {
+		id: record.id,
+		origin,
+		state: {
+			kind: "directory",
+			overlay: readDirectoryOverlayRecord(record.state.overlay)
+		}
+	};
+	const rawState = record.state;
+	if (rawState.kind === "file") {
+		const mode = rawState.mode;
+		if (mode !== "100644" && mode !== "100755") throw new Error(`Invalid file workdir node state mode: ${String(mode)}`);
+		const contentRef = rawState.contentRef;
+		if (contentRef !== void 0 && contentRef !== null && typeof contentRef !== "string") throw new Error("Invalid file workdir node content ref");
+		return {
+			id: record.id,
+			origin,
+			state: {
+				kind: "file",
+				mode,
+				content: contentRef === void 0 || contentRef === null ? void 0 : readPayload(contentDir, contentRef)
+			}
+		};
+	}
+	if (rawState.kind !== "symlink") throw new Error(`Invalid file workdir node state kind: ${String(rawState.kind)}`);
+	const targetRef = rawState.targetRef;
+	if (targetRef !== void 0 && targetRef !== null && typeof targetRef !== "string") throw new Error("Invalid file workdir node target ref");
+	return {
+		id: record.id,
+		origin,
+		state: {
+			kind: "symlink",
+			mode: "120000",
+			target: targetRef === void 0 || targetRef === null ? void 0 : readPayload(contentDir, targetRef)
+		}
+	};
+}
+function readDirectoryOverlayRecord(value) {
+	if (!isFileDirectoryOverlayPayload(value)) throw new Error("Invalid file workdir directory overlay payload");
+	return {
+		addedEntries: new Map(value.addedEntries.map(([name, nodeId]) => [name, nodeId])),
+		deletedNames: new Set(value.deletedNames)
+	};
+}
+function isFileDirectoryOverlayPayload(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const maybe = value;
+	if (!Array.isArray(maybe.addedEntries) || !Array.isArray(maybe.deletedNames)) return false;
+	const hasValidAddedEntries = maybe.addedEntries.every((entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && typeof entry[1] === "string");
+	const hasValidDeletedNames = maybe.deletedNames.every((name) => typeof name === "string");
+	return hasValidAddedEntries && hasValidDeletedNames;
+}
+function restoreOrigin(record) {
+	const origin = record;
+	if (origin.kind === "none") return { kind: "none" };
+	if (origin.kind === "repo-tree") {
+		if (typeof origin.hash !== "string" || origin.hash.length === 0) throw new Error("Invalid file workdir node: repo-tree origin is missing hash");
+		return {
+			kind: "repo-tree",
+			hash: origin.hash
+		};
+	}
+	if (origin.kind !== "repo-blob") throw new Error(`Invalid file workdir node origin kind: ${String(origin.kind)}`);
+	if (typeof origin.hash !== "string" || origin.hash.length === 0) throw new Error("Invalid file workdir node: repo-blob origin is missing hash");
+	if (origin.mode !== "100644" && origin.mode !== "100755" && origin.mode !== "120000") throw new Error(`Invalid file workdir node origin mode: ${String(origin.mode)}`);
+	return {
+		kind: "repo-blob",
+		mode: origin.mode,
+		hash: origin.hash
+	};
+}
+function readPayload(contentDir, payloadRef) {
+	const path = getContentPath(contentDir, payloadRef);
+	if (!existsSync(path)) throw new Error(`Virtual workdir payload not found: ${payloadRef}`);
+	return readFileSync(path);
+}
+function readJson(path) {
+	return JSON.parse(readFileSync(path, "utf-8"));
+}
+function writeJsonAtomic(path, value) {
+	writeBufferAtomic(path, Buffer.from(JSON.stringify(value), "utf-8"));
+}
+function writeBufferAtomic(path, value) {
+	mkdirSync(dirname(path), { recursive: true });
+	const tempPath = `${path}.tmp`;
+	writeFileSync(tempPath, value);
+	renameSync(tempPath, path);
+}
+function encodePathToken(value) {
+	return encodeURIComponent(value);
+}
+function decodePathToken(value) {
+	return decodeURIComponent(value);
+}
+//#endregion
+export { createFileVirtualWorkdirBackend };

package/dist/workdir/file.d.mts

@@ -0,0 +1,2 @@
+import { CreateFileVirtualWorkdirBackendOptions, createFileVirtualWorkdirBackend } from "./file-backend.mjs";
+export { type CreateFileVirtualWorkdirBackendOptions, createFileVirtualWorkdirBackend };

package/dist/workdir/file.mjs

@@ -0,0 +1,2 @@
+import { createFileVirtualWorkdirBackend } from "./file-backend.mjs";
+export { createFileVirtualWorkdirBackend };

package/dist/workdir/ids.d.mts

@@ -0,0 +1,7 @@
+//#region src/workdir/ids.d.ts
+/** 会话内节点的稳定身份 */
+type NodeId = string & {
+  readonly __brand: "NodeId";
+};
+//#endregion
+export { NodeId };

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

@@ -0,0 +1,17 @@
+import { VirtualWorkdirBackend } from "./core.mjs";
+
+//#region src/workdir/memory-backend.d.ts
+/**
+ * 创建内存版 Virtual Workdir backend
+ *
+ * @example
+ * ```ts
+ * const backend = createMemoryVirtualWorkdirBackend();
+ * const sessionId = backend.createSession({ baseTree: tree });
+ * const session = backend.openSession(repo.objects, sessionId);
+ * expect(session.baseTree).toBe(tree);
+ * ```
+ */
+declare function createMemoryVirtualWorkdirBackend(): VirtualWorkdirBackend;
+//#endregion
+export { createMemoryVirtualWorkdirBackend };