feat: enhance file history management and add user prompt checkpointing

Author: qorzj

src/common/file-history.ts

@@ -9,12 +9,12 @@ const MANIFEST_PATH = ".deepcode-file-history.json";
 
 type FileHistoryEntry = {
   path: string;
-  blob: string;
+  blob: string | null;
   mode: "100644";
 };
 
 type FileHistoryManifest = {
-  version: 1;
+  version: 1 | 2;
   files: Record<string, FileHistoryEntry>;
 };
 
@@ -85,7 +85,11 @@ export class GitFileHistory {
       for (const filePath of absolutePaths) {
         const key = this.getFileKey(filePath);
         if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
-          delete manifest.files[key];
+          manifest.files[key] = {
+            path: filePath,
+            blob: null,
+            mode: "100644",
+          };
           continue;
         }
 
@@ -110,6 +114,24 @@ export class GitFileHistory {
     }
   }
 
+  recordTrackedFilesCheckpoint(sessionId: string, message: string): string | undefined {
+    const currentHash = this.ensureSession(sessionId);
+    if (!currentHash) {
+      return undefined;
+    }
+
+    try {
+      const manifest = this.readManifest(currentHash);
+      const trackedPaths = Object.values(manifest.files).map((entry) => entry.path);
+      if (trackedPaths.length === 0) {
+        return currentHash;
+      }
+      return this.recordCheckpoint(sessionId, trackedPaths, message);
+    } catch {
+      return undefined;
+    }
+  }
+
   canRestore(sessionId: string, checkpointHash: string): boolean {
     if (!isCommitHash(checkpointHash)) {
       return false;
@@ -146,18 +168,49 @@ export class GitFileHistory {
 
     for (const [key, entry] of Object.entries(currentManifest.files)) {
       if (!targetManifest.files[key]) {
-        removeTrackedFile(entry.path);
+        this.restoreFirstKnownEntry(currentHash, key, entry.path);
       }
     }
 
     for (const entry of Object.values(targetManifest.files)) {
+      if (!entry.blob) {
+        removeTrackedFile(entry.path);
+        continue;
+      }
       fs.mkdirSync(path.dirname(entry.path), { recursive: true });
       fs.writeFileSync(entry.path, this.readBlob(entry.blob));
     }
 
     this.runGit(["update-ref", branchRef, checkpointHash]);
   }
 
+  private restoreFirstKnownEntry(currentHash: string | undefined, key: string, fallbackPath: string): void {
+    const firstEntry = currentHash ? this.findFirstKnownEntry(currentHash, key) : undefined;
+    const entry = firstEntry ?? { path: fallbackPath, blob: null, mode: "100644" as const };
+    if (!entry.blob) {
+      removeTrackedFile(entry.path);
+      return;
+    }
+
+    fs.mkdirSync(path.dirname(entry.path), { recursive: true });
+    fs.writeFileSync(entry.path, this.readBlob(entry.blob));
+  }
+
+  private findFirstKnownEntry(currentHash: string, key: string): FileHistoryEntry | undefined {
+    const commitHashes = this.runGit(["rev-list", "--reverse", currentHash])
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(isCommitHash);
+
+    for (const commitHash of commitHashes) {
+      const entry = this.readManifest(commitHash).files[key];
+      if (entry) {
+        return entry;
+      }
+    }
+    return undefined;
+  }
+
   private getSessionBranchRef(sessionId: string): string | null {
     if (!/^[A-Za-z0-9._-]+$/.test(sessionId)) {
       return null;
@@ -182,6 +235,9 @@ export class GitFileHistory {
     const entries: string[] = [`100644 blob ${manifestBlob}\t${MANIFEST_PATH}\0`];
 
     for (const [key, entry] of Object.entries(normalizedManifest.files)) {
+      if (!entry.blob) {
+        continue;
+      }
       entries.push(`${entry.mode} blob ${entry.blob}\t${key}\0`);
     }
 
@@ -191,7 +247,12 @@ export class GitFileHistory {
   private readManifest(commitHash: string): FileHistoryManifest {
     const buffer = this.runGitBuffer(["cat-file", "blob", `${commitHash}:${MANIFEST_PATH}`]);
     const parsed = JSON.parse(buffer.toString("utf8")) as FileHistoryManifest;
-    if (!parsed || parsed.version !== 1 || !parsed.files || typeof parsed.files !== "object") {
+    if (
+      !parsed ||
+      (parsed.version !== 1 && parsed.version !== 2) ||
+      !parsed.files ||
+      typeof parsed.files !== "object"
+    ) {
       throw new Error("Invalid file history manifest.");
     }
     return normalizeManifest(parsed);
@@ -256,13 +317,18 @@ export class GitFileHistory {
 }
 
 function emptyManifest(): FileHistoryManifest {
-  return { version: 1, files: {} };
+  return { version: 2, files: {} };
 }
 
 function normalizeManifest(manifest: FileHistoryManifest): FileHistoryManifest {
   const files: Record<string, FileHistoryEntry> = {};
   for (const [key, entry] of Object.entries(manifest.files).sort(([left], [right]) => left.localeCompare(right))) {
-    if (!isValidStoredPath(key) || !entry || entry.mode !== "100644" || !isCommitHash(entry.blob)) {
+    if (
+      !isValidStoredPath(key) ||
+      !entry ||
+      entry.mode !== "100644" ||
+      (entry.blob !== null && !isCommitHash(entry.blob))
+    ) {
       throw new Error("Invalid file history manifest.");
     }
     files[key] = {
@@ -271,7 +337,7 @@ function normalizeManifest(manifest: FileHistoryManifest): FileHistoryManifest {
       mode: "100644",
     };
   }
-  return { version: 1, files };
+  return { version: 2, files };
 }
 
 function uniqueAbsolutePaths(filePaths: string[]): string[] {

src/session.ts

@@ -1013,6 +1013,7 @@ The candidate skills are as follows:\n\n`;
       this.appendSessionMessage(sessionId, instructionsMessage);
     }
 
+    this.recordUserPromptCheckpoint(sessionId);
     const userMessage = this.buildUserMessage(sessionId, userPrompt);
     this.appendSessionMessage(sessionId, userMessage);
 
@@ -1087,6 +1088,7 @@ ${skillMd}
     this.reportNewPrompt();
 
     this.ensureFileHistorySession(sessionId);
+    this.recordUserPromptCheckpoint(sessionId);
     const userMessage = this.buildUserMessage(sessionId, userPrompt);
     this.appendSessionMessage(sessionId, userMessage);
 
@@ -1752,6 +1754,10 @@ ${skillMd}
     return this.getFileHistory().getCurrentCheckpointHash(sessionId);
   }
 
+  private recordUserPromptCheckpoint(sessionId: string): string | undefined {
+    return this.getFileHistory().recordTrackedFilesCheckpoint(sessionId, "User prompt checkpoint");
+  }
+
   private prepareFileMutationCheckpoint(sessionId: string, filePath: string): void {
     const fileHistory = this.getFileHistory();
     const previousHash = fileHistory.ensureSession(sessionId);

src/tests/session.test.ts

@@ -999,6 +999,68 @@ test("createSession initializes file-history repo and session branch", async (t)
   );
 });
 
+test("createSession initializes an empty file-history manifest without scanning existing files", async (t) => {
+  if (!hasGit()) {
+    t.skip("git is not available");
+    return;
+  }
+
+  const workspace = createTempDir("deepcode-file-history-empty-init-workspace-");
+  const home = createTempDir("deepcode-file-history-empty-init-home-");
+  setHomeDir(home);
+  fs.writeFileSync(path.join(workspace, "unrelated.txt"), "keep me\n", "utf8");
+  fs.mkdirSync(path.join(workspace, "nested"));
+  fs.writeFileSync(path.join(workspace, "nested", "another.txt"), "also keep me\n", "utf8");
+
+  const manager = createSessionManager(workspace, "machine-id-file-history-empty-init");
+  (manager as any).activateSession = async () => {};
+
+  const sessionId = await manager.createSession({ text: "first prompt" });
+  const userMessage = manager.listSessionMessages(sessionId).find((message) => message.role === "user");
+  assert.ok(userMessage?.checkpointHash);
+
+  const manifest = readFileHistoryManifest(home, workspace, userMessage.checkpointHash);
+  assert.deepEqual(manifest.files, {});
+});
+
+test("replySession snapshots manual edits to tracked files before appending the user prompt", async (t) => {
+  if (!hasGit()) {
+    t.skip("git is not available");
+    return;
+  }
+
+  const workspace = createTempDir("deepcode-prompt-checkpoint-manual-edit-workspace-");
+  const home = createTempDir("deepcode-prompt-checkpoint-manual-edit-home-");
+  setHomeDir(home);
+
+  const filePath = path.join(workspace, "hello_world.py");
+  const manager = createSessionManager(workspace, "machine-id-prompt-checkpoint-manual-edit");
+  (manager as any).activateSession = async () => {};
+
+  const sessionId = await manager.createSession({ text: "create hello world" });
+  const gitDir = getFileHistoryGitDir(home, workspace);
+  const fileHistory = new GitFileHistory(workspace, gitDir);
+
+  fs.writeFileSync(filePath, 'print("Hello, World!")\n', "utf8");
+  assert.ok(fileHistory.recordCheckpoint(sessionId, [filePath], "created hello world"));
+
+  const manualEdit = 'if name == main:\n  print("Hello, World!")\n';
+  fs.writeFileSync(filePath, manualEdit, "utf8");
+  await manager.replySession(sessionId, { text: "I manually edited @hello_world.py, note it" });
+  const manualEditUserMessage = manager
+    .listSessionMessages(sessionId)
+    .filter((message) => message.role === "user")
+    .at(-1);
+  assert.ok(manualEditUserMessage?.checkpointHash);
+
+  fs.writeFileSync(filePath, 'if __name__ == "__main__":\n  print("Hello, World!")\n', "utf8");
+  assert.ok(fileHistory.recordCheckpoint(sessionId, [filePath], "fixed hello world"));
+
+  manager.restoreSessionCode(sessionId, manualEditUserMessage.id);
+
+  assert.equal(fs.readFileSync(filePath, "utf8"), manualEdit);
+});
+
 test("Write tool advances file-history while preserving the user prompt checkpoint", async (t) => {
   if (!hasGit()) {
     t.skip("git is not available");
@@ -1191,6 +1253,8 @@ test("restoreSessionCode restores project files from the recorded Git checkpoint
   const manager = createSessionManager(workspace, "machine-id-undo-code");
   const sessionId = "session-code-restore";
   const checkpointHash = createFileHistoryCommit(home, workspace, sessionId, { "tracked.txt": "before\n" });
+  const fileHistory = new GitFileHistory(workspace, getFileHistoryGitDir(home, workspace));
+  assert.ok(fileHistory.recordCheckpoint(sessionId, [path.join(workspace, "new.txt")], "pre-create new.txt"));
   createFileHistoryCommit(home, workspace, sessionId, { "tracked.txt": "after\n", "new.txt": "remove me\n" });
   fs.writeFileSync(path.join(workspace, "tracked.txt"), "after\n", "utf8");
   fs.writeFileSync(path.join(workspace, "new.txt"), "remove me\n", "utf8");
@@ -1206,6 +1270,91 @@ test("restoreSessionCode restores project files from the recorded Git checkpoint
   assert.equal(fs.existsSync(path.join(workspace, "new.txt")), false);
 });
 
+test("restoreSessionCode preserves files that predate their first tracked mutation", async (t) => {
+  if (!hasGit()) {
+    t.skip("git is not available");
+    return;
+  }
+
+  const workspace = createTempDir("deepcode-undo-preexisting-files-workspace-");
+  const home = createTempDir("deepcode-undo-preexisting-files-home-");
+  setHomeDir(home);
+
+  const readmePath = path.join(workspace, "README.md");
+  const readmeEnPath = path.join(workspace, "README-en.md");
+  const readmeZhPath = path.join(workspace, "README-zh_CN.md");
+  fs.writeFileSync(readmePath, "这是一个hello world演示项目\n", "utf8");
+  fs.writeFileSync(readmeEnPath, "This is a hello world demo project.\n", "utf8");
+  fs.writeFileSync(readmeZhPath, "", "utf8");
+
+  const manager = createSessionManager(workspace, "machine-id-undo-preexisting-files");
+  const sessionId = "session-undo-preexisting-files";
+  const gitDir = getFileHistoryGitDir(home, workspace);
+  const fileHistory = new GitFileHistory(workspace, gitDir);
+  fileHistory.ensureSession(sessionId);
+
+  const targetCheckpoint = fileHistory.recordCheckpoint(
+    sessionId,
+    [readmePath, readmeEnPath],
+    "checkpoint before syncing all readmes"
+  );
+  assert.ok(targetCheckpoint);
+
+  assert.ok(fileHistory.recordCheckpoint(sessionId, [readmeZhPath], "pre-sync zh readme"));
+  fs.writeFileSync(readmePath, "Synced readme\n", "utf8");
+  fs.writeFileSync(readmeEnPath, "Synced readme\n", "utf8");
+  fs.writeFileSync(readmeZhPath, "Synced readme\n", "utf8");
+  assert.ok(fileHistory.recordCheckpoint(sessionId, [readmePath, readmeEnPath, readmeZhPath], "synced readmes"));
+
+  (manager as any).appendSessionMessage(sessionId, {
+    ...buildTestMessage("user-with-readme-checkpoint", sessionId, "user", "sync README*.md"),
+    checkpointHash: targetCheckpoint,
+  });
+
+  manager.restoreSessionCode(sessionId, "user-with-readme-checkpoint");
+
+  assert.equal(fs.readFileSync(readmePath, "utf8"), "这是一个hello world演示项目\n");
+  assert.equal(fs.readFileSync(readmeEnPath, "utf8"), "This is a hello world demo project.\n");
+  assert.equal(fs.readFileSync(readmeZhPath, "utf8"), "");
+});
+
+test("restoreSessionCode restores deleted tracked files and leaves unrelated files alone", async (t) => {
+  if (!hasGit()) {
+    t.skip("git is not available");
+    return;
+  }
+
+  const workspace = createTempDir("deepcode-undo-deleted-files-workspace-");
+  const home = createTempDir("deepcode-undo-deleted-files-home-");
+  setHomeDir(home);
+
+  const trackedPath = path.join(workspace, "tracked.txt");
+  const unrelatedPath = path.join(workspace, "unrelated.txt");
+  fs.writeFileSync(trackedPath, "before delete\n", "utf8");
+  fs.writeFileSync(unrelatedPath, "do not touch\n", "utf8");
+
+  const manager = createSessionManager(workspace, "machine-id-undo-deleted-files");
+  const sessionId = "session-undo-deleted-files";
+  const gitDir = getFileHistoryGitDir(home, workspace);
+  const fileHistory = new GitFileHistory(workspace, gitDir);
+  fileHistory.ensureSession(sessionId);
+  const targetCheckpoint = fileHistory.recordCheckpoint(sessionId, [trackedPath], "before delete");
+  assert.ok(targetCheckpoint);
+
+  fs.unlinkSync(trackedPath);
+  assert.ok(fileHistory.recordCheckpoint(sessionId, [trackedPath], "after delete"));
+
+  (manager as any).appendSessionMessage(sessionId, {
+    ...buildTestMessage("user-before-delete", sessionId, "user", "restore deleted file"),
+    checkpointHash: targetCheckpoint,
+  });
+
+  manager.restoreSessionCode(sessionId, "user-before-delete");
+
+  assert.equal(fs.readFileSync(trackedPath, "utf8"), "before delete\n");
+  assert.equal(fs.readFileSync(unrelatedPath, "utf8"), "do not touch\n");
+});
+
 test("replySession /continue runs trailing pending tool calls before requesting another response", async () => {
   const workspace = createTempDir("deepcode-continue-tool-workspace-");
   const home = createTempDir("deepcode-continue-tool-home-");
@@ -2617,6 +2766,18 @@ function createFileHistoryCommit(
   return commitHash;
 }
 
+function getFileHistoryGitDir(home: string, workspace: string): string {
+  const projectCode = workspace.replace(/[\\/]/g, "-").replace(/:/g, "");
+  return path.join(home, ".deepcode", "projects", projectCode, "file-history", ".git");
+}
+
+function readFileHistoryManifest(home: string, workspace: string, checkpointHash: string): any {
+  const gitDir = getFileHistoryGitDir(home, workspace);
+  return JSON.parse(
+    runFileHistoryGit(gitDir, workspace, ["cat-file", "blob", `${checkpointHash}:.deepcode-file-history.json`])
+  );
+}
+
 function runFileHistoryGit(
   gitDir: string,
   workspace: string,