fix(studio-server): history writes and claims follow Studio's write rule (#7988)

History undo, restore and Cmd+Z now leave alone every file that Studio's
file routes refuse to write. This covers tool-trusted, private, hidden and
node_modules paths, and scripts the project's package.json runs. Cmd+Z
passes over an edit that only changed such files. A claim no longer takes
such a file's pending change.

A claim's `overwrote` version now counts only when the server itself saw
that version at that path. A version stored for another file can no longer
become a file's earlier state.

The write rule also refuses more files that tools and agents load on
their own: opencode and crush settings, compose override files,
Dockerfile.* and Containerfile, every lefthook spelling, mise, nodemon,
devbox, wrangler, vercel and netlify settings, *.config.jsonc,
tsconfig.*.json, Taskfile.dist, simple-git-hooks, Ruby build files, and
.nix and .fish scripts.
This commit is contained in:
Michael Wang
2026-11-17 00:48:03 +00:00
committed by GitHub
parent 5979991d5f
commit 32fe10a8b3
7 changed files with 358 additions and 26 deletions
+5
View File
@@ -1874,6 +1874,11 @@ lists the newer entries. Run it again with `--just-this` to put back only that
entry's files over the newer edits, or `--back-to-before` to go back to before
it, undoing the newer entries too.
`undo` and `restore` put back only files that Studio itself may write. Package
and lock files, tool and agent configuration, scripts that `package.json` runs,
and hidden or private files keep their current content. Change those in your
editor.
## Render to a file
### `render`
+33
View File
@@ -387,6 +387,33 @@ describe("toolTrustedFileKind", () => {
["gulpfile.mjs", "tool-config"],
["turbo.json", "tool-config"],
["pyproject.toml", "tool-config"],
["opencode.json", "tool-config"],
["opencode.jsonc", "tool-config"],
["crush.json", "tool-config"],
["docker-compose.override.yml", "tool-config"],
["compose.override.yaml", "tool-config"],
["Dockerfile.dev", "tool-config"],
["web.dockerfile", "tool-config"],
["Containerfile", "tool-config"],
["lefthook-local.yml", "tool-config"],
["lefthook.json", "tool-config"],
["lefthook.toml", "tool-config"],
["Taskfile.dist.yml", "tool-config"],
["nodemon.json", "tool-config"],
["mise.toml", "tool-config"],
["mise.local.toml", "tool-config"],
["mise/config.toml", "tool-config"],
["eslint.config.jsonc", "tool-config"],
["tsconfig.app.json", "tool-config"],
["simple-git-hooks.json", "tool-config"],
["devbox.json", "tool-config"],
["wrangler.jsonc", "tool-config"],
["Gemfile", "tool-config"],
["Vagrantfile", "tool-config"],
["shell.nix", "program"],
["hooks/pre-commit.fish", "program"],
["NODEMON.JSON.", "tool-config"],
["Docker\ufb01le.dev", "tool-config"],
] as const)("names %s %s", (path, kind) => {
expect(toolTrustedFileKind(path)).toBe(kind);
});
@@ -411,6 +438,12 @@ describe("toolTrustedFileKind", () => {
"media/take~2.mp4",
"assets/scene~10.png",
"assets/config.json",
"compositions/docker.html",
"assets/mise-en-scene.png",
"assets/lefthook.png",
"assets/compose.svg",
"config.toml",
"assets/script.js",
])("leaves %s to the other rules", (path) => {
expect(toolTrustedFileKind(path)).toBeNull();
});
+40 -12
View File
@@ -132,29 +132,51 @@ const TOOL_CONFIG_FILES = new Set([
"makefile",
"gnumakefile",
"justfile",
"dockerfile",
"procfile",
"lefthook.yml",
"lefthook.yaml",
"turbo.json",
"nx.json",
"docker-compose.yml",
"docker-compose.yaml",
"compose.yml",
"compose.yaml",
"taskfile.yml",
"taskfile.yaml",
"pyproject.toml",
// Agents that read their settings, including commands to run, from the project folder.
"opencode.json",
"opencode.jsonc",
"crush.json",
// Dev servers, environment managers and deploy CLIs that run a command the file names.
"nodemon.json",
"devbox.json",
"devenv.yaml",
"wrangler.toml",
"wrangler.json",
"wrangler.jsonc",
"vercel.json",
"netlify.toml",
"composer.json",
// Ruby and other build files that are code in their own right.
"rakefile",
"gemfile",
"vagrantfile",
"tiltfile",
"earthfile",
"brewfile",
]);
// The same tools' other spellings and the files they load alongside their main config.
const TOOL_CONFIG_FAMILIES = [
/^(?:docker-)?compose(?:\.override)?\.ya?ml$/,
/^(?:dockerfile|containerfile)(?:\..+)?$|\.(?:docker|container)file$/,
/^lefthook(?:-local)?\.(?:ya?ml|jsonc?|toml)$/,
/^taskfile(?:\.dist)?\.ya?ml$/,
/^mise(?:\.[^.]+)*\.toml$/,
/^simple-git-hooks\.(?:json|[cm]?js)$/,
/^[jt]sconfig\..+\.json$/,
];
// Tools load these on their own: vite.config.ts, jest.config.json, docker-compose.yml, gulpfile.js and the like.
const TOOL_CONFIG =
/\.config\.(?:[cm]?[jt]sx?|json5?|ya?ml|toml)$|^(?:gulp|grunt)file\.[cm]?[jt]s$/;
/\.config\.(?:[cm]?[jt]sx?|json[c5]?|ya?ml|toml)$|^(?:gulp|grunt)file\.[cm]?[jt]s$/;
// Coding agents load these on their own, wherever they sit.
const AGENT_INSTRUCTIONS =
/^(agents?|claude|gemini|qwen|crush|warp|conventions|copilot-instructions)(\.[a-z]+)?\.md$/;
// Programs and scripts a shell, an OS or another tool runs; a browser composition never needs them.
const PROGRAM_EXTENSIONS =
"exe com bat cmd ps1 psm1 vbs vbe wsf hta msi scr pif cpl lnk dll so dylib node sh bash zsh command jar appimage py rb pl php".split(
"exe com bat cmd ps1 psm1 vbs vbe wsf hta msi scr pif cpl lnk dll so dylib node sh bash zsh fish command jar appimage py rb pl php nix".split(
" ",
);
const PROGRAM = new RegExp(`\\.(?:${PROGRAM_EXTENSIONS.join("|")})$`);
@@ -174,6 +196,12 @@ function isShortName(segment: string): boolean {
return !extension || TRUSTED_EXTENSIONS.some((trusted) => trusted.startsWith(extension));
}
function isToolConfig(name: string, segments: readonly string[]): boolean {
if (TOOL_CONFIG_FILES.has(name) || TOOL_CONFIG.test(name)) return true;
if (TOOL_CONFIG_FAMILIES.some((family) => family.test(name))) return true;
return name === "config.toml" && segments.at(-2) === "mise";
}
/** What makes a file one another program runs or trusts; see `toolTrustedFileKind`. */
export type ToolTrustedKind =
| "short-name"
@@ -195,7 +223,7 @@ export function toolTrustedFileKind(relPath: string): ToolTrustedKind | null {
if (segments.some(isShortName)) return "short-name";
if (PROJECT_CONFIG_FILES.has(name)) return "project-config";
if (LOCK_FILES.has(name)) return "lock-file";
if (TOOL_CONFIG_FILES.has(name) || TOOL_CONFIG.test(name)) return "tool-config";
if (isToolConfig(name, segments)) return "tool-config";
if (AGENT_INSTRUCTIONS.test(name)) return "agent-instructions";
if (PROGRAM.test(name)) return "program";
return null;
@@ -3,7 +3,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { isPrivateProjectFile, walkDir } from "./safePath";
import { isPrivateProjectFile, isWritableProjectFile, walkDir } from "./safePath";
const hooks = vi.hoisted(() => ({ unreadable: new Map<string, string>() }));
vi.mock("node:fs", async (importOriginal) => {
@@ -131,3 +131,43 @@ describe("isPrivateProjectFile", () => {
expect(isPrivateProjectFile("/p", "/p/sub/index.html")).toBe(false);
});
});
describe("isWritableProjectFile and the project's package.json", () => {
function projectRunning(pkg: object) {
const projectDir = createProjectDir();
writeFileSync(join(projectDir, "package.json"), JSON.stringify(pkg));
return (path: string) => isWritableProjectFile(projectDir, join(projectDir, path));
}
it("refuses the script files package.json runs, in any spelling the write rule folds", () => {
const writable = projectRunning({
main: "server.js",
bin: { tool: "./bin/tool.mjs" },
scripts: { build: "node ./build.mjs && tsx scripts/gen.ts --out=dist", dev: "vite" },
});
for (const path of ["server.js", "Server.JS", "bin/tool.mjs", "build.mjs", "scripts/gen.ts"])
expect(writable(path), path).toBe(false);
});
it("still writes composition scripts, folders and files package.json does not name", () => {
const writable = projectRunning({ scripts: { build: "vite build --outDir dist" } });
for (const path of ["script.js", "compositions/scene.js", "dist", "index.html"])
expect(writable(path), path).toBe(true);
});
it("reads a package.json changed since the last write", () => {
const projectDir = createProjectDir();
const pkg = join(projectDir, "package.json");
writeFileSync(pkg, JSON.stringify({ scripts: {} }));
expect(isWritableProjectFile(projectDir, join(projectDir, "run.js"))).toBe(true);
writeFileSync(pkg, JSON.stringify({ scripts: { start: "node run.js" } }));
expect(isWritableProjectFile(projectDir, join(projectDir, "run.js"))).toBe(false);
});
it("writes as before when package.json is missing or not JSON", () => {
const projectDir = createProjectDir();
expect(isWritableProjectFile(projectDir, join(projectDir, "server.js"))).toBe(true);
writeFileSync(join(projectDir, "package.json"), "{ not json");
expect(isWritableProjectFile(projectDir, join(projectDir, "server.js"))).toBe(true);
});
});
+63 -2
View File
@@ -1,5 +1,5 @@
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { lstatSync, readdirSync, type Dirent } from "node:fs";
import { lstatSync, readdirSync, readFileSync, statSync, type Dirent } from "node:fs";
import {
isStudioPrivatePath,
mkdirWithinProject,
@@ -70,9 +70,70 @@ export function isWritableProjectPath(relPath: string): boolean {
}
export function isWritableProjectFile(projectDir: string, filePath: string): boolean {
return projectRelatives(projectDir, filePath).every(isWritableProjectPath);
return projectRelatives(projectDir, filePath).every((path) =>
isWritableInProject(projectDir, path),
);
}
/** `isWritableProjectPath`, and not a script the project's package.json runs. */
export function isWritableInProject(projectDir: string, relPath: string): boolean {
return isWritableProjectPath(relPath) && !scriptsPackageRuns(projectDir).has(foldedPath(relPath));
}
// A word in package.json that names a JavaScript or TypeScript file: `node server.js`, `tsx ./scripts/build.ts`.
const SCRIPT_FILE = /\.[cm]?[jt]sx?$/;
const SHELL_WORD_BREAKS = /[\s;&|()<>"'`=,]+/;
const NO_SCRIPTS: ReadonlySet<string> = new Set();
const packageScripts = new Map<string, { stat: string; files: ReadonlySet<string> }>();
const foldedPath = (path: string): string =>
projectPathSegments(path)
.filter((segment) => segment !== "" && segment !== ".")
.join("/");
/**
* The script files the project's package.json runs (its `main`, `bin` and every script file its scripts name), folded
* as `projectPathSegments` folds. npm, node or a tool runs these with the developer's rights.
*/
function scriptsPackageRuns(projectDir: string): ReadonlySet<string> {
const path = join(projectDir, "package.json");
const stat = statSync(path, { throwIfNoEntry: false });
if (!stat?.isFile()) return NO_SCRIPTS;
const key = `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
const cached = packageScripts.get(path);
if (cached?.stat === key) return cached.files;
const files = scriptFilesNamedBy(readPackageJson(path));
packageScripts.set(path, { stat: key, files });
return files;
}
function readPackageJson(path: string): unknown {
try {
return JSON.parse(readFileSync(path, "utf-8"));
} catch {
return null;
}
}
function scriptFilesNamedBy(pkg: unknown): ReadonlySet<string> {
if (!pkg || typeof pkg !== "object") return NO_SCRIPTS;
const { main, bin, scripts }: { main?: unknown; bin?: unknown; scripts?: unknown } = pkg;
const words = [main, ...valuesOf(bin), ...valuesOf(scripts)].flatMap((value) =>
typeof value === "string" ? value.split(SHELL_WORD_BREAKS) : [],
);
const files = words.filter(
(word) => SCRIPT_FILE.test(word) && !word.split(/[\\/]/).includes(".."),
);
return new Set(files.map(foldedPath));
}
const valuesOf = (value: unknown): unknown[] =>
typeof value === "string"
? [value]
: value && typeof value === "object"
? Object.values(value)
: [];
/**
* The first `toolTrustedFileKind` file, `node_modules` or `.git` below `dir`, which a delete or move of the folder
* would take along. Links are not followed.
@@ -23,7 +23,7 @@ import {
onFileOverwritten,
recordFileWriteReceipt,
} from "../helpers/fileVersion.js";
import { realFilePath } from "../helpers/safePath.js";
import { isWritableInProject, realFilePath } from "../helpers/safePath.js";
import {
STUDIO_SIGNATURE_MANIFEST_PATHS,
affectsProjectSignature,
@@ -370,6 +370,23 @@ function chainBackFrom(
return chain;
}
const SEEN_PER_PATH = 32;
/** Per path, the latest hashes the server itself found or replaced there; a claim's word counts only for these. */
class SeenVersions extends Map<string, Set<string>> {
note(path: string, hash: string): void {
const hashes = this.get(path) ?? new Set<string>();
hashes.delete(hash);
hashes.add(hash);
const oldest = hashes.values().next().value;
if (hashes.size > SEEN_PER_PATH && oldest !== undefined) hashes.delete(oldest);
this.set(path, hashes);
}
sawAt(path: string, hash: string | undefined): string | undefined {
return hash && this.get(path)?.has(hash) ? hash : undefined;
}
}
/** Files one change to a group; a later change to the same path keeps the group's first "before". */
function addChange(group: Group, path: string, before: string | null, after: string | null): void {
const earlier = group.changes.get(path);
@@ -392,11 +409,15 @@ function keepTargetsOfItsFiles(entry: HistoryEntry): HistoryEntry {
/** The tracked files; any change owes the project's video-state.json a rewrite. */
class TrackedFiles extends Map<string, Tracked> {
constructor(private readonly changed: () => void) {
constructor(
private readonly changed: () => void,
private readonly seen: (path: string, hash: string) => void,
) {
super();
}
override set(path: string, file: Tracked): this {
this.changed();
this.seen(path, file.hash);
return super.set(path, file);
}
override delete(path: string): boolean {
@@ -412,7 +433,11 @@ class Engine {
readonly home: string;
log: HistoryLog = { baseline: new Map(), entries: [], pins: new Set() };
owesVideoState = true;
tracked = new TrackedFiles(() => (this.owesVideoState = true));
seen = new SeenVersions();
tracked = new TrackedFiles(
() => (this.owesVideoState = true),
(path, hash) => this.seen.note(path, hash),
);
windows: Group[] = [];
outside: Group | null = null;
/** A coalescing claim, open until another key, its idle timer, an operation, a window, or another write. */
@@ -556,6 +581,8 @@ class Engine {
if (!replaced || replaced === after) return;
const path = relative(realDir, absPath).split(sep).join("/");
if (!isHistoryPath(path)) return;
this.seen.note(path, replaced);
this.seen.note(path, after);
// One chain per file, a new Map per write (forgetWritesBefore checks identity); off-chain notes were overwritten.
this.overwritten.set(
path,
@@ -919,6 +946,8 @@ class Engine {
: null;
}
studioWouldWrite = (path: string): boolean => isWritableInProject(this.dir, path);
logPath(path: string): string {
return relative(this.dir, resolve(this.dir, path)).split(sep).join("/");
}
@@ -929,12 +958,12 @@ class Engine {
paths: readonly string[],
overwrote: Readonly<Record<string, string>>,
): Promise<HistoryFileChange[]> {
const wanted = new Set(paths.map((path) => this.logPath(path)));
const wanted = new Set(paths.map((path) => this.logPath(path)).filter(this.studioWouldWrite));
const at = new Map(
Object.entries(overwrote).map(([path, version]) => [
this.logPath(path),
hashOfVersion(version),
]),
Object.entries(overwrote).map(([path, version]) => {
const logPath = this.logPath(path);
return [logPath, this.seen.sawAt(logPath, hashOfVersion(version))];
}),
);
const others = this.windows.filter((open) => !sameWho(open.who, who));
const groups = this.outside ? [this.outside, ...others] : others;
@@ -1239,7 +1268,10 @@ class Engine {
): Promise<HistoryEntry | null> {
this.assertWritable();
const changes = [...target]
.filter(([path, hash]) => (this.tracked.get(path)?.hash ?? null) !== hash)
.filter(
([path, hash]) =>
this.studioWouldWrite(path) && (this.tracked.get(path)?.hash ?? null) !== hash,
)
.sort(([, a], [, b]) => Number(a !== null) - Number(b !== null));
const setAsideByDeletesFirst = new Set(
changes.filter(([, hash]) => hash === null).map(([path]) => this.tracked.get(path)?.hash),
@@ -1344,8 +1376,9 @@ class Engine {
next(direction: "back" | "forward", who: HistoryWho): HistoryEntry | undefined {
// An outside change has no known author, so it is everyone's; a step commits it after the held claim.
const mine = (author: HistoryWho) => sameWho(author, who) || sameWho(author, OUTSIDE);
const writes = (paths: Iterable<string>) => [...paths].some(this.studioWouldWrite);
const pending = [...[...this.windows].reverse(), this.outside, this.claimed?.group].find(
(group) => group?.changes.size && mine(group.who),
(group) => group && writes(group.changes.keys()) && mine(group.who),
);
if (pending) return direction === "back" ? this.pendingEntry(pending) : undefined;
const everyone = this.options.undoScope === "everyone";
@@ -1354,7 +1387,9 @@ class Engine {
return stepTarget(
this.log.entries,
direction,
(entry) => entry.files.length > 0 && (mine(entry.who) || (everyone && !ofOpenTurn(entry))),
(entry) =>
writes(entry.files.map((file) => file.path)) &&
(mine(entry.who) || (everyone && !ofOpenTurn(entry))),
);
}
@@ -0,0 +1,130 @@
// @vitest-environment node
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { createStudioApi } from "../createStudioApi";
import { fileContentVersion } from "../helpers/fileVersion";
import { openProjectHistory } from "../history/projectHistory";
import type { StudioApiAdapter } from "../types";
const cleanup: Array<() => unknown> = [];
afterEach(async () => {
for (const step of cleanup.splice(0).reverse()) await step();
});
function tempDir(prefix: string): string {
const dir = mkdtempSync(join(tmpdir(), prefix));
cleanup.push(() => rmSync(dir, { recursive: true, force: true }));
return dir;
}
const PACKAGE = JSON.stringify({ scripts: { build: "node ./build.mjs" } });
const AGENT = { kind: "agent", name: "Agent" };
interface Reply {
windowId?: string;
claimed?: { id: string } | null;
back?: unknown;
}
type Call = (path: string, body?: object) => Promise<Reply>;
async function project(files: Record<string, string>) {
const projectDir = tempDir("hf-history-protected-");
const write = (path: string, text: string) => writeFileSync(join(projectDir, path), text);
for (const [path, text] of Object.entries(files)) write(path, text);
const history = await openProjectHistory({
projectDir,
historyRoot: tempDir("hf-history-root-"),
});
cleanup.push(() => history.close());
const api = createStudioApi({
listProjects: () => [],
resolveProject: (id: string) => (id === "demo" ? { id, dir: projectDir } : null),
history: () => history,
} as unknown as StudioApiAdapter);
const call: Call = async (path, body) => {
const init = body ? { method: "POST", body: JSON.stringify(body) } : undefined;
const response = await api.request(`/projects/demo/history${path}`, init);
expect(response.status, path).toBe(200);
return (await response.json()) as Reply;
};
const read = (path: string) => readFileSync(join(projectDir, path), "utf-8");
const has = (path: string) => existsSync(join(projectDir, path));
return { write, read, has, call };
}
async function agentTurn(call: Call, edit: () => void): Promise<string> {
const { windowId } = await call("/window", { label: "Agent turn", who: AGENT });
edit();
await call(`/window/${windowId}/close`, {});
return windowId ?? "";
}
describe("history writes and the files Studio does not write", () => {
it("undo and restore bring back compositions and leave tool-trusted files as they stand", async () => {
const { write, read, has, call } = await project({
"index.html": "A",
"package.json": PACKAGE,
"AGENTS.md": "rules",
"build.mjs": "build",
});
const turn = await agentTurn(call, () => {
write("index.html", "B");
write("AGENTS.md", "planted rules");
write("build.mjs", "planted build");
write("opencode.json", "{}");
});
const untouched = () => [read("AGENTS.md"), read("build.mjs"), has("opencode.json")];
await call("/undo", { entryId: turn });
expect(read("index.html")).toBe("A");
expect(untouched()).toEqual(["planted rules", "planted build", true]);
await agentTurn(call, () => write("index.html", "C"));
await call("/restore", { point: "start" });
expect(read("index.html")).toBe("A");
expect(untouched()).toEqual(["planted rules", "planted build", true]);
});
it("Cmd+Z passes over an outside edit that only changed a tool-trusted file", async () => {
const { write, read, call } = await project({ "index.html": "A", "package.json": PACKAGE });
const edited = JSON.stringify({ scripts: {} });
write("package.json", edited);
expect((await call("")).back).toBeNull();
expect(await call("/step", { direction: "back" })).toEqual({ ok: true, entry: null });
expect(read("package.json")).toBe(edited);
});
it("a claim cannot make bytes stored for another file a file's earlier state", async () => {
const { write, read, call } = await project({ "index.html": "A", "other.html": "EVIL" });
write("index.html", "B");
const { claimed } = await call("/claim", {
paths: ["index.html"],
overwrote: { "index.html": fileContentVersion("EVIL") },
});
expect(claimed?.id).toBeTruthy();
await call("/undo", { entryId: claimed?.id });
expect(read("index.html")).toBe("A");
});
it("a claim cannot take an outside change to package.json", async () => {
const { write, read, call } = await project({
"index.html": "A",
"package.json": PACKAGE,
"evil.html": "EVIL",
});
const edited = JSON.stringify({ name: "edited by the developer" });
write("package.json", edited);
const { claimed } = await call("/claim", {
paths: ["package.json"],
overwrote: { "package.json": fileContentVersion("EVIL") },
});
expect(claimed).toBeNull();
expect(read("package.json")).toBe(edited);
});
});