Files
hyperframes/packages/cli/src/utils/historyOwner.ts
T
Miguel Ángel e2bfdf2224 fix(cli): keep check from waiting on project history another process holds (#5759)
* fix(cli): keep check from waiting on project history another process holds

* fix(cli): name the history skip instead of commenting it
2026-10-17 16:52:46 +00:00

289 lines
11 KiB
TypeScript

import { randomUUID } from "node:crypto";
import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import {
DEFAULT_HISTORY_ROOT,
HistoryBusyError,
MAX_WINDOW_IDLE_MS,
openProjectHistory,
readProjectHistory,
type HistoryEntry,
type HistoryListItem,
type HistoryResult,
type HistoryWho,
type UndoMode,
} from "@hyperframes/studio-server/history";
import { resolveProject } from "./project.js";
import { findPreviewServerForProject, studioApiUrl } from "./studioSelectionClient.js";
export type { UndoMode };
/** An agent's turn: its writes until `end`, or until the idle limit passes without one, are one entry of its own. */
export interface Turn {
via: "preview" | "direct";
id: string;
who: HistoryWho;
label: string;
startedAt: number;
lastWriteAt: number;
/** Entries this turn already filed: without a preview, each command mid-turn files the turn so far. */
parts: string[];
}
/** Whoever holds the project's history: a running preview (over its routes) or this process (the engine). */
export interface Owner {
via: "preview" | "direct";
list(): Promise<HistoryListItem[]>;
peek(point: string): Promise<Record<string, string> | null>;
blob(hash: string): Promise<Buffer>;
undo(id: string, who: HistoryWho, mode?: UndoMode): Promise<HistoryResult>;
restore(point: string, who: HistoryWho): Promise<HistoryEntry | null>;
pin(id: string, pinned: boolean): Promise<void>;
begin(
who: HistoryWho,
label: string,
exclusive?: boolean,
): Promise<{ id: string; startedAt: number }>;
end(id: string): Promise<HistoryEntry | null>;
checkpoint(): Promise<void>;
close(): Promise<void>;
}
export type Reader = Pick<Owner, "via" | "list" | "peek" | "blob">;
/** Swapped by tests. */
export const historyDeps = {
historyRoot: resolve(process.env.HYPERFRAMES_HISTORY_ROOT || DEFAULT_HISTORY_ROOT),
findServer: (projectDir: string) => findPreviewServerForProject(projectDir),
/** A turn with no write for this long has ended, through a preview or not. */
turnIdleMs: MAX_WINDOW_IDLE_MS,
ownerWaitMs: undefined as number | undefined,
now: () => Date.now(),
};
/** A refusal is the caller's to fix: commands print its message, never a stack. */
export class Refusal extends Error {}
const turnFile = (dir: string) => join(dir, ".hyperframes", "history-turn.json");
/** The open turn, or null; a marker with no last write time cannot say when the turn ended, so it has. */
function readTurn(dir: string): Turn | null {
try {
const turn = JSON.parse(readFileSync(turnFile(dir), "utf-8")) as Turn;
return typeof turn.lastWriteAt === "number" ? { ...turn, parts: turn.parts ?? [] } : null;
} catch {
return null;
}
}
export function writeTurn(dir: string, turn: Turn | null): void {
if (!turn) return rmSync(turnFile(dir), { force: true });
mkdirSync(dirname(turnFile(dir)), { recursive: true });
writeFileSync(turnFile(dir), JSON.stringify(turn));
}
/** Each agent's last ended turn, as the entries it filed; kept beside the marker, outside the history. */
const lastTurnsFile = (dir: string) => join(dir, ".hyperframes", "history-turns.json");
function readLastTurns(dir: string): Record<string, string[]> {
try {
const turns: unknown = JSON.parse(readFileSync(lastTurnsFile(dir), "utf-8"));
return turns && typeof turns === "object" ? (turns as Record<string, string[]>) : {};
} catch {
return {};
}
}
/** The entries of `name`'s last ended turn; null when `name` never ended a turn here. */
export function lastTurnParts(dir: string, name: string): string[] | null {
return readLastTurns(dir)[name] ?? null;
}
type TurnKey = Pick<HistoryEntry, "who" | "label" | "startedAt">;
const samePart = (a: TurnKey, b: TurnKey) =>
a.who.kind === b.who.kind &&
a.who.name === b.who.name &&
a.label === b.label &&
a.startedAt === b.startedAt;
/** Ends an open turn: its last part is the entry `end` returns, and every part is kept as its agent's last turn. */
export async function endTurn(
owner: Owner,
turn: Turn,
dir: string,
): Promise<{ entry: HistoryEntry | null; parts: string[] }> {
const entry = await owner.end(turn.id);
// A Studio claim can cut a turn: each cut part is an entry with the turn's who, label and start.
const cut = (await owner.list()).filter((other) => samePart(other, entry ?? turn));
const own = entry ? [entry.id] : [];
const parts = [...new Set([...turn.parts, ...cut.map((part) => part.id), ...own])];
// Recorded before the marker goes, so a crash between the two never leaves the older turn as the last one.
const draft = `${lastTurnsFile(dir)}.${process.pid}.tmp`;
mkdirSync(dirname(draft), { recursive: true });
writeFileSync(draft, JSON.stringify({ ...readLastTurns(dir), [turn.who.name]: parts }));
renameSync(draft, lastTurnsFile(dir));
writeTurn(dir, null);
return { entry, parts };
}
function previewOwner(route: (path: string) => string): Owner {
const call = async (path: string, body?: object, signal?: AbortSignal) => {
const init = {
...(body && {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(body),
}),
...(signal && { signal }),
};
const response = await fetch(route(path), init);
if (response.ok) return response;
const error = (await response.json().catch(() => null)) as { error?: string } | null;
throw new Refusal(error?.error ?? `The preview answered ${response.status}.`);
};
const json = async (path: string, body?: object, signal?: AbortSignal) =>
(await call(path, body, signal)).json();
const list = async () => (await json("")).entries as HistoryListItem[];
return {
via: "preview",
list,
peek: async (point) => (await json(`/peek/${encodeURIComponent(point)}`)).files,
blob: async (hash) => Buffer.from(await (await call(`/blob/${hash}`)).arrayBuffer()),
undo: (id, who, mode) => json("/undo", { entryId: id, who, mode }),
restore: (point, who) => json("/restore", { point, who }),
pin: async (id, pinned) => void (await json("/pin", { entryId: id, pinned })),
begin: async (who, label, exclusive) => {
const opened = await json("/window", {
who,
label,
idleMs: historyDeps.turnIdleMs,
...(exclusive && { exclusive: true }),
});
return { id: opened.windowId, startedAt: opened.startedAt ?? historyDeps.now() };
},
// A preview restarted since begin committed the window on its way down.
end: (id) =>
json(`/window/${id}/close`, {})
.then((closed) => closed.entry as HistoryEntry | null)
.catch(async () => (await list()).find((entry) => entry.id === id) ?? null),
checkpoint: async () => void (await json("/checkpoint", {}, AbortSignal.timeout(5_000))),
close: async () => {},
};
}
async function directOwner(
projectDir: string,
ownerWaitMs = historyDeps.ownerWaitMs,
): Promise<{ owner: Owner; turn: Turn | null }> {
let turn: Turn | null = null;
const history = await openProjectHistory({
projectDir,
historyRoot: historyDeps.historyRoot,
now: () => historyDeps.now(),
pruneGoneProjectsBudgetMs: 1000,
ownerWaitMs,
closedWindowAfterOwnership: () => {
turn = readTurn(projectDir);
return turn
? {
id: turn.id,
who: turn.who,
label: turn.label,
startedAt: turn.startedAt,
lastWriteAt: turn.lastWriteAt,
idleMs: historyDeps.turnIdleMs,
}
: undefined;
},
});
return {
turn,
owner: {
via: "direct",
list: async () => history.list(),
peek: async (point) => history.peek(point),
blob: (hash) => history.readBlob(hash),
undo: (id, who, mode) => history.undo(id, { who, ...(mode && { mode }) }),
restore: (point, who) => history.restore(point, who),
pin: async (id, pinned) => history.pin(id, pinned),
// Opening filed every earlier write; the turn's own writes are filed to it when the next open passes it.
begin: async () => ({ id: randomUUID(), startedAt: historyDeps.now() }),
end: async (id) => history.list().find((entry) => entry.id === id) ?? null,
checkpoint: () => history.checkpoint(),
close: () => history.close(),
},
};
}
/** One owner: a preview that keeps this project's history, else the engine, which refuses a second opener. */
async function connect(
projectDir: string,
ownerWaitMs?: number,
): Promise<{ owner: Owner; turn: Turn | null }> {
const server = await historyDeps.findServer(projectDir);
if (server) {
const route = (path: string) => studioApiUrl(server, `history${path}`);
// 404, or gone since the scan: no preview keeps this history, and the engine's lock guards the rest.
const status = await fetch(route("")).then(
(response) => response.status,
() => 404,
);
if (status !== 404) return { owner: previewOwner(route), turn: readTurn(projectDir) };
}
return directOwner(projectDir, ownerWaitMs);
}
/** Runs `task` with the project's history. ponytail: with no preview, a command mid-turn splits the turn in two. */
export async function withOwner<T>(
dir: string | undefined,
task: (owner: Owner, turn: Turn | null, projectDir: string) => Promise<T>,
{ ownerWaitMs }: { ownerWaitMs?: number } = {},
): Promise<T> {
const { dir: projectDir } = resolveProject(dir);
const { owner, turn } = await connect(projectDir, ownerWaitMs);
try {
return await task(owner, turn, projectDir);
} finally {
// This open filed the turn so far under its id; the turn goes on under a fresh one, from its last write.
try {
if (owner.via === "direct" && turn) {
const kept = (await owner.list()).find((entry) => entry.id === turn.id);
if (readTurn(projectDir)?.id === turn.id) {
const lastWriteAt = kept ? kept.endedAt : turn.lastWriteAt;
const parts = kept ? [...turn.parts, kept.id] : turn.parts;
writeTurn(projectDir, { ...turn, via: "direct", id: randomUUID(), lastWriteAt, parts });
}
}
} finally {
await owner.close();
}
}
}
export async function withReader<T>(
dir: string | undefined,
task: (reader: Reader) => Promise<T>,
): Promise<T> {
try {
return await withOwner(dir, (owner) => task(owner));
} catch (error) {
if (!(error instanceof HistoryBusyError)) throw error;
}
// Busy is only thrown on opening, so the task has not run; an open turn's marker is left as it is.
const view = readProjectHistory({
projectDir: resolveProject(dir).dir,
historyRoot: historyDeps.historyRoot,
});
return task({
via: "direct",
list: async () => view.list(),
peek: async (point) => view.peek(point),
// The owner may have pruned a blob since its log was read.
blob: (hash) =>
view.readBlob(hash).catch((error: NodeJS.ErrnoException) => {
throw error.code === "ENOENT" ? new Refusal("That point is no longer kept") : error;
}),
});
}