fix(studio-server): history refuses once closed and reopens when a new project takes its folder

Author: miguel-heygen

packages/cli/src/commands/history.test.ts

@@ -1,6 +1,14 @@
 // @vitest-environment node
 import { spawn } from "node:child_process";
-import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import type { AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -16,7 +24,7 @@ import { runCommand } from "citty";
 import { Hono } from "hono";
 import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";
 import { consumeCommandResult } from "../utils/commandResult.js";
-import { historyDeps } from "../utils/historyOwner.js";
+import { historyDeps, withOwner } from "../utils/historyOwner.js";
 import historyCommand from "./history.js";
 
 const pause = (ms: number) => new Promise((settle) => setTimeout(settle, ms));
@@ -247,6 +255,24 @@ describe.each(["direct", "preview"])("hyperframes history (%s)", (mode) => {
 });
 
 describe("hyperframes history, one owner", () => {
+  it("lets go of the history when a new project takes the folder's path mid-command", async () => {
+    const { dir, hf } = project();
+    await hf("begin", "--who", "claude", "--label", "Retitle");
+    const moved = `${dir}-moved`;
+    onTestFinished(() => rmSync(moved, { recursive: true, force: true }));
+    const swap = async () => {
+      renameSync(dir, moved);
+      mkdirSync(dir);
+    };
+    await expect(withOwner(dir, swap)).rejects.toThrow("now another project");
+    const reopened = await openProjectHistory({
+      projectDir: moved,
+      historyRoot: historyDeps.historyRoot,
+      ownerWaitMs: 200,
+    });
+    await reopened.close();
+  });
+
   it("goes through a running preview, so the log keeps one baseline and every entry once", async () => {
     const { dir, json, turn } = project();
     const held = await preview(dir);
@@ -400,6 +426,7 @@ describe("hyperframes history, one owner", () => {
       env: {
         ...process.env,
         HOME: home,
+        USERPROFILE: home,
         HYPERFRAMES_SKIP_UPDATE_CHECK: "1",
         HYPERFRAMES_NO_TELEMETRY: "1",
       },

packages/cli/src/server/studioServer.test.ts

@@ -1,12 +1,21 @@
 import { EventEmitter } from "node:events";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import {
   createProjectSignature,
   fileContentVersion,
   HistoryBusyError,
+  HistoryClosedError,
 } from "@hyperframes/studio-server";
 import { loadHyperframeRuntimeSource } from "@hyperframes/core";
 import { loadRuntimeSource } from "./runtimeSource.js";
@@ -156,16 +165,38 @@ describe("createStudioServer project history (D-491)", () => {
     await server.shutdown();
   });
 
-  it("tries a history another process was holding again on the next request, instead of turning it off", async () => {
-    historyState.open = async () => {
-      historyState.open = null;
-      throw new HistoryBusyError(1);
-    };
+  it.each([
+    ["another process was holding", new HistoryBusyError(1)],
+    ["whose folder changed while it opened", new HistoryClosedError("now another project")],
+  ])(
+    "tries a history %s again on the next request, instead of turning it off",
+    async (_, refusal) => {
+      historyState.open = async () => {
+        historyState.open = null;
+        throw refusal;
+      };
+      const projectDir = tmpProject();
+      server = createStudioServer({ projectDir, historyRoot: tmpProject() });
+      const historyUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
+      expect((await server.app.request(historyUrl)).status).toBe(404);
+      expect((await server.app.request(historyUrl)).status).toBe(200);
+      await server.shutdown();
+    },
+  );
+
+  it("opens a new project's own history once it takes the folder's path", async () => {
     const projectDir = tmpProject();
+    writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
     server = createStudioServer({ projectDir, historyRoot: tmpProject() });
     const historyUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
-    expect((await server.app.request(historyUrl)).status).toBe(404);
     expect((await server.app.request(historyUrl)).status).toBe(200);
+    renameSync(projectDir, `${projectDir}-moved`);
+    dirs.push(`${projectDir}-moved`);
+    mkdirSync(projectDir);
+    writeFileSync(join(projectDir, "index.html"), "<html>new</html>");
+
+    expect((await server.app.request(historyUrl)).status).toBe(200);
+    expect(existsSync(join(projectDir, ".hyperframes", "history-id"))).toBe(true);
     await server.shutdown();
   });
 

packages/cli/src/server/studioServer.ts

@@ -56,7 +56,8 @@ import {
   DEFAULT_HISTORY_ROOT,
   openProjectHistory,
   HistoryBusyError,
-  type ProjectHistory,
+  HistoryClosedError,
+  historyCache,
 } from "@hyperframes/studio-server";
 import { resolveAutoProxy } from "../utils/projectConfig.js";
 import { getElementScreenshotClip } from "@hyperframes/studio-server/screenshot-clip";
@@ -429,18 +430,20 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
 
   // Opened on first use, so a server that never serves Studio's history never writes one. A failed open stays off
   // for this run; one another process was holding is tried again on the next request.
-  let history: Promise<ProjectHistory | null> | undefined;
-  const projectHistory = () =>
-    (history ??= openProjectHistory({
+  const histories = historyCache(() =>
+    openProjectHistory({
       projectDir,
       historyRoot: options.historyRoot ?? DEFAULT_HISTORY_ROOT,
     }).catch((error: unknown) => {
       console.warn(`[studio] Project history is off: ${String(error)}`);
-      if (error instanceof HistoryBusyError) history = undefined;
+      if (error instanceof HistoryBusyError || error instanceof HistoryClosedError)
+        histories.forget(projectDir);
       return null;
-    }));
+    }),
+  );
+  const projectHistory = () => histories.get(projectDir);
   watcher.addListener((changedPath) => {
-    void history?.then((opened) => opened?.noteChange(changedPath));
+    void histories.peek(projectDir)?.then((opened) => opened?.noteChange(changedPath));
   });
 
   const inFlightRenders = new Map<AbortController, Promise<void>>();
@@ -1098,7 +1101,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
   const shutdown = async (): Promise<void> => {
     shuttingDown = true;
     // Commits any open edit window; bounded with the renders below, so a history still opening cannot hold exit.
-    const closeHistory = history?.then((opened) => opened?.close()).catch(() => {});
+    const closeHistory = histories.closeAll().catch(() => {});
     const renders = [...inFlightRenders];
     for (const [abortController] of renders) abortController.abort();
     const { killTrackedProcesses, closeBrowserPool } = await import("@hyperframes/engine");

packages/cli/src/utils/historyOwner.ts

@@ -210,8 +210,12 @@ export async function withOwner<T>(
   } finally {
     // This open filed the turn so far under its id; the turn goes on under a fresh one, from its last write.
     const direct = owner.via === "direct" && turn;
-    const kept = direct && (await owner.list()).find((entry) => entry.id === turn.id);
-    await owner.close();
+    let kept: HistoryListItem | undefined;
+    try {
+      kept = direct ? (await owner.list()).find((entry) => entry.id === turn.id) : undefined;
+    } finally {
+      await owner.close();
+    }
     if (direct && readTurn(projectDir)?.id === turn.id) {
       const lastWriteAt = kept ? kept.endedAt : turn.lastWriteAt;
       const parts = kept ? [...turn.parts, kept.id] : turn.parts;

packages/studio-server/src/history/blobStore.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { constants, createReadStream } from "node:fs";
+import { constants, createReadStream, renameSync } from "node:fs";
 import { copyFile, mkdir, readdir, readFile, rename, rm, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
@@ -10,7 +10,7 @@ export interface BlobStore {
   has(hash: string): boolean;
   read(hash: string): Promise<Buffer>;
   /** Writes the blob's bytes to `absPath` by clone-or-copy and rename, so a reader never sees half a file. */
-  writeTo(hash: string, absPath: string): Promise<void>;
+  writeTo(hash: string, absPath: string, beforeReplace?: () => void): Promise<void>;
   bytes(): number;
   size(hash: string): number;
   prune(keep: ReadonlySet<string>): Promise<void>;
@@ -24,12 +24,13 @@ async function hashFile(path: string): Promise<string> {
   return hash.digest("hex");
 }
 
-async function cloneOrCopy(from: string, to: string): Promise<void> {
+async function cloneOrCopy(from: string, to: string, beforeReplace?: () => void): Promise<void> {
   await mkdir(dirname(to), { recursive: true });
   const temp = `${to}.${randomUUID()}.tmp`;
   try {
     await copyFile(from, temp, constants.COPYFILE_FICLONE);
-    await rename(temp, to);
+    beforeReplace?.();
+    renameSync(temp, to);
   } catch (error) {
     await rm(temp, { force: true });
     throw error;
@@ -70,7 +71,8 @@ export async function openBlobStore(dir: string): Promise<BlobStore> {
     },
     has: (hash) => sizes.has(hash),
     read: async (hash) => readFile(pathOf(hash)),
-    writeTo: async (hash, absPath) => cloneOrCopy(pathOf(hash), absPath),
+    writeTo: async (hash, absPath, beforeReplace) =>
+      cloneOrCopy(pathOf(hash), absPath, beforeReplace),
     bytes: () => total,
     size: (hash) => sizes.get(hash) ?? 0,
     async prune(keep) {

packages/studio-server/src/history/historyCache.ts

@@ -0,0 +1,28 @@
+import type { ProjectHistory } from "./projectHistory.js";
+
+type Opened = Promise<ProjectHistory | null>;
+
+/** A host's histories, one per project folder, opened on first use; a new project at the path gets its own. */
+export function historyCache(open: (projectDir: string) => Opened) {
+  const histories = new Map<string, Opened>();
+  const get = async (projectDir: string): Promise<ProjectHistory | null> => {
+    let cached = histories.get(projectDir);
+    if (!cached) histories.set(projectDir, (cached = open(projectDir)));
+    const opened = await cached;
+    if (!opened?.replacedAtPath()) return opened;
+    const reopen = () => open(projectDir);
+    if (histories.get(projectDir) === cached)
+      histories.set(projectDir, opened.close().then(reopen, reopen));
+    return get(projectDir);
+  };
+  return {
+    get,
+    /** The history if one was opened, without opening it. */
+    peek: (projectDir: string) => histories.get(projectDir),
+    forget: (projectDir: string) => histories.delete(projectDir),
+    closeAll: () =>
+      Promise.all(
+        [...histories.values()].map((opened) => opened.then((history) => history?.close())),
+      ),
+  };
+}

packages/studio-server/src/history/historyId.ts

@@ -1,12 +1,13 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { replaceFileAtomically } from "../helpers/atomicFile.js";
 
 export const ID_PATH = join(".hyperframes", "history-id");
 /** The only shape minted here; the id is project content and becomes a path, so nothing else is trusted. */
 const ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
-function readId(projectDir: string): string | null {
+export function readId(projectDir: string): string | null {
   try {
     const id = readFileSync(join(projectDir, ID_PATH), "utf-8").trim();
     return ID_SHAPE.test(id) ? id : null;
@@ -15,28 +16,42 @@ function readId(projectDir: string): string | null {
   }
 }
 
-function recordedDir(historyDir: string): string | null {
+export type FolderIdentity = { ino: number; birthtimeMs: number };
+
+export const sameFolder = (a: FolderIdentity, b: FolderIdentity) =>
+  a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+
+export function isRecordedFolder(historyDir: string, folder: FolderIdentity): boolean {
   try {
-    return JSON.parse(readFileSync(join(historyDir, "project.json"), "utf-8")).dir ?? null;
+    const was = JSON.parse(readFileSync(join(historyDir, "project.json"), "utf-8"));
+    return sameFolder({ ino: was.ino, birthtimeMs: was.born }, folder);
   } catch {
-    return null;
+    return false;
   }
 }
 
 /**
- * The project's history id, kept in the project so a rename or move keeps its history. A folder whose id is
- * still carried by the folder that history was recorded for is a copy, and gets an id of its own.
+ * The project's history id, kept in the project so a rename or move keeps its history. Where history exists under it,
+ * only the recorded folder keeps it: same inode and creation time, since an inode alone is reused after a delete.
  */
 export function projectHistoryId(projectDir: string, historyRoot: string): string {
   const dir = resolve(projectDir);
+  const folder = statSync(dir);
   let id = readId(dir);
-  const was = id && recordedDir(join(historyRoot, id));
-  if (!id || (was && was !== dir && existsSync(was) && readId(was) === id)) {
+  if (
+    !id ||
+    (existsSync(join(historyRoot, id)) && !isRecordedFolder(join(historyRoot, id), folder))
+  ) {
     id = randomUUID();
     mkdirSync(join(dir, ".hyperframes"), { recursive: true });
     writeFileSync(join(dir, ID_PATH), `${id}\n`);
   }
-  mkdirSync(join(historyRoot, id), { recursive: true });
-  writeFileSync(join(historyRoot, id, "project.json"), JSON.stringify({ dir }));
+  recordProject(join(historyRoot, id), dir, folder);
   return id;
 }
+
+export function recordProject(historyDir: string, dir: string, folder: FolderIdentity): void {
+  const record = { dir, ino: folder.ino, born: folder.birthtimeMs };
+  mkdirSync(historyDir, { recursive: true });
+  replaceFileAtomically(join(historyDir, "project.json"), JSON.stringify(record), 0o644);
+}

packages/studio-server/src/history/historyLog.ts

@@ -42,7 +42,7 @@ export interface HistoryLog {
   pins: Set<string>;
 }
 
-type LogRecord =
+export type LogRecord =
   | { type: "baseline"; files: Record<string, string> }
   | { type: "entry"; entry: HistoryEntry }
   | { type: "pin"; id: string; pinned: boolean };