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);

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/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,12 @@
 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";
 
 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 +15,41 @@ function readId(projectDir: string): string | null {
   }
 }
 
-function recordedDir(historyDir: string): string | null {
+type Recorded = { dir?: string; dev?: number; ino?: number };
+
+function recorded(historyDir: string): Recorded | null {
   try {
-    return JSON.parse(readFileSync(join(historyDir, "project.json"), "utf-8")).dir ?? null;
+    return JSON.parse(readFileSync(join(historyDir, "project.json"), "utf-8"));
   } catch {
     return null;
   }
 }
 
+function isCopy(
+  was: Recorded,
+  id: string,
+  dir: string,
+  folder: { dev: number; ino: number },
+): boolean {
+  if (!was.dir || (was.ino === folder.ino && was.dev === folder.dev)) return false;
+  return was.dir === dir ? was.ino !== undefined : existsSync(was.dir) && readId(was.dir) === id;
+}
+
 /**
- * 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. A folder carrying the id of
+ * a recorded folder that still has it, or standing where another recorded folder was, is a copy: it gets its own id.
  */
 export function projectHistoryId(projectDir: string, historyRoot: string): string {
   const dir = resolve(projectDir);
+  const { dev, ino } = statSync(dir);
   let id = readId(dir);
-  const was = id && recordedDir(join(historyRoot, id));
-  if (!id || (was && was !== dir && existsSync(was) && readId(was) === id)) {
+  const was = id && recorded(join(historyRoot, id));
+  if (!id || (was && isCopy(was, id, dir, { dev, ino }))) {
     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 }));
+  writeFileSync(join(historyRoot, id, "project.json"), JSON.stringify({ dir, dev, ino }));
   return id;
 }