diff --git a/knip.json b/knip.json index 1f4956faa6..111f022102 100644 --- a/knip.json +++ b/knip.json @@ -16,7 +16,12 @@ "playwright-ct": false, "workspaces": { "src": { - "entry": ["extension.ts!", "extension/api.ts!", "workers/countTokens.ts!"], + "entry": [ + "extension.ts!", + "extension/api.ts!", + "workers/countTokens.ts!", + "services/file-safety/safeWriteText.ts!" + ], "project": [ "**/*.ts!", "!**/__tests__/**!", diff --git a/src/__tests__/removeClineFromStack-delegation.spec.ts b/src/__tests__/removeClineFromStack-delegation.spec.ts index 0db228662e..e032f74dc4 100644 --- a/src/__tests__/removeClineFromStack-delegation.spec.ts +++ b/src/__tests__/removeClineFromStack-delegation.spec.ts @@ -1,10 +1,12 @@ // npx vitest run __tests__/removeClineFromStack-delegation.spec.ts import { describe, it, expect, vi } from "vitest" +import { RooCodeEventName } from "@roo-code/types" import { ClineProvider } from "../core/webview/ClineProvider" import { TaskRegistry } from "../core/task/TaskRegistry" import { PendingActionSettlementError, type Task } from "../core/task/Task" import { makeProviderStub } from "./helpers/provider-stub" +import { writeToFileTool } from "../core/tools/WriteToFileTool" type PrivateClineProviderMethods = { removeClineFromStack: (this: ClineProvider) => ReturnType @@ -202,6 +204,55 @@ describe("ClineProvider failed history restoration cleanup", () => { expect(task.dispose).toHaveBeenCalledOnce() }) + it("releases the tool's per-task state before a directly disposed task loses its listeners", async () => { + const key = "failed-history-task.inst-1" + const order: string[] = [] + // The listener identity matters: the release must detach THIS function, so the + // fixture binds it to a variable instead of an anonymous inline no-op. + const abortCleanup = vi.fn() + const task = { + taskId: "failed-history-task", + instanceId: "inst-1", + emit: vi.fn(), + once: vi.fn(), + off: vi.fn(), + dispose: vi.fn().mockImplementation(() => { + // Dispose removes every listener, so this is the last moment the abort + // cleanup could still have run; the entry must already be gone here. + order.push(writeToFileTool["taskPartialStreamState"].has(key) ? "state-retained" : "state-cleared") + order.push("dispose") + return Promise.resolve() + }), + } as unknown as Task + // Fixture: the state entry the tool would have created during a partial stream. + writeToFileTool["taskPartialStreamState"].set(key, { + lastSeenPartialPath: undefined, + streamFailed: false, + differentPathStream: false, + // The entry stands for a stream whose path never stabilized, so it never owned the view. + ownsPreview: false, + streamError: undefined, + task, + abortCleanup, + }) + const taskEventListeners = new Map([[task, [vi.fn()]]]) + const taskRegistry = new TaskRegistry() + taskRegistry.push(task) + const provider = { taskRegistry, taskEventListeners, log: vi.fn() } as unknown as ClineProvider + + await privateClineProvider.cleanupFailedHistoryTask.call( + provider, + task, + new PendingActionSettlementError("settlement failed"), + ) + + expect(order).toEqual(["state-cleared", "dispose"]) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + // Dropping the map entry is not enough: the registered TaskAborted listener must + // be detached with the same function reference it was registered with. + expect(task.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortCleanup) + }) + it("keeps the task active after an unrelated history resume failure", async () => { const cleanupListener = vi.fn() const task = { diff --git a/src/core/assistant-message/__tests__/presentAssistantMessage.spec.ts b/src/core/assistant-message/__tests__/presentAssistantMessage.spec.ts index eb9b095bc0..b6048488ce 100644 --- a/src/core/assistant-message/__tests__/presentAssistantMessage.spec.ts +++ b/src/core/assistant-message/__tests__/presentAssistantMessage.spec.ts @@ -5,6 +5,7 @@ import { presentAssistantMessage } from "../presentAssistantMessage" import { DispatchState, transitionDispatch } from "../../task/dispatchState" import type { Task } from "../../task/Task" import type { RequestPolicySnapshot } from "../../prompts/tools/effective-tool-policy" +import { writeToFileTool } from "../../tools/WriteToFileTool" vi.mock("../../task/Task") vi.mock("@roo-code/telemetry", () => ({ @@ -106,3 +107,76 @@ describe("transitionDispatch", () => { expect(() => transitionDispatch(from, to)).toThrow("invalid transition") }) }) +describe("a dropped tool call still runs the parse-failure teardown", () => { + // The dropped call is answered before the tool is dispatched, so this is the only + // point where the per-task state a streaming delta registered outside execute() + // can still be torn down. + let task: Task + let pushToolResultToUserContent: Mock + + beforeEach(() => { + pushToolResultToUserContent = vi.fn().mockReturnValue(true) + task = { + taskId: "task-id", + instanceId: "instance-id", + abort: false, + didRejectTool: false, + didAlreadyUseTool: false, + consecutiveMistakeCount: 0, + consecutiveMistakeLimit: 3, + dispatchState: DispatchState.IDLE, + pendingWork: null, + currentStreamingContentIndex: 0, + assistantMessageContent: [ + { type: "tool_use", id: "call-1", name: "write_to_file", params: {}, partial: false }, + ] as unknown as Task["assistantMessageContent"], + userMessageContent: [], + didCompleteReadingStream: false, + activeToolContexts: new Map(), + say: vi.fn().mockResolvedValue(undefined), + recordToolError: vi.fn(), + pushToolResultToUserContent, + getTaskMode: vi.fn().mockResolvedValue("code"), + } as unknown as Task + }) + + afterEach(() => { + vi.restoreAllMocks() + }) + + it("runs the teardown for the dropped call and keeps the generic error when it reports nothing", async () => { + const teardownSpy = vi.spyOn(writeToFileTool, "onParameterParseFailure").mockResolvedValue(false) + + await presentAssistantMessage(task, snapshot) + + expect(teardownSpy).toHaveBeenCalledTimes(1) + expect(teardownSpy).toHaveBeenCalledWith( + task, + expect.objectContaining({ toolCallId: "call-1" }), + expect.objectContaining({ message: expect.stringContaining("missing nativeArgs") }), + ) + expect(pushToolResultToUserContent).toHaveBeenCalledTimes(1) + expect(pushToolResultToUserContent.mock.calls[0][0]).toEqual( + expect.objectContaining({ type: "tool_result", tool_use_id: "call-1", is_error: true }), + ) + expect(String(pushToolResultToUserContent.mock.calls[0][0].content)).toContain("missing nativeArgs") + }) + + it("puts the reported streaming error in the one tool_result instead of the generic text", async () => { + const teardownSpy = vi + .spyOn(writeToFileTool, "onParameterParseFailure") + .mockImplementationOnce(async (_task, callbacks, _parseError) => { + await callbacks.handleError("writing file", new Error("ENOSPC: no space left on device, write")) + return true + }) + + await presentAssistantMessage(task, snapshot) + + expect(teardownSpy).toHaveBeenCalledTimes(1) + expect(pushToolResultToUserContent).toHaveBeenCalledTimes(1) + const payload = pushToolResultToUserContent.mock.calls[0][0] + expect(String(payload.content)).toContain("ENOSPC: no space left on device, write") + expect(String(payload.content)).not.toContain("missing nativeArgs") + expect(payload.tool_use_id).toBe("call-1") + }) +}) diff --git a/src/core/assistant-message/presentAssistantMessage.ts b/src/core/assistant-message/presentAssistantMessage.ts index 73d48b2e7c..57cfe8e200 100644 --- a/src/core/assistant-message/presentAssistantMessage.ts +++ b/src/core/assistant-message/presentAssistantMessage.ts @@ -12,6 +12,7 @@ import { t } from "../../i18n" import { defaultModeSlug, getModeBySlug } from "../../shared/modes" import type { AutoApprovalContext, ToolResponse, ToolUse, McpToolUse } from "../../shared/tools" +import type { ToolCallbacks } from "../tools/BaseTool" import { buildAutoDenyReason } from "../auto-approval" @@ -71,6 +72,51 @@ export function toTelemetryToolName( return "invalid_tool_call" } +/** + * The one tool instance the parse-failure teardown can act on for a dropped call. + * + * write_to_file is the only tool that overrides onParameterParseFailure(); every other tool + * inherits the base no-op that reports nothing and tears nothing down, so resolving those + * names here would only add a call with no effect. Unknown, MCP, and custom-tool names + * resolve to no tool. + */ +function parseFailureTeardownTool(toolName: string) { + return toolName === "write_to_file" ? writeToFileTool : undefined +} + +/** + * Run the parse-failure teardown for a known tool whose call never reached handle(). + * + * The dispatch-scope callbacks do not exist at the point where the call is dropped, so this + * builds the ToolCallbacks shape the teardown expects and points both report paths at the + * caller instead of pushing a second payload: the caller keeps owning the single tool_result + * the dropped call must carry, and the returned text tells it which error to put in it. The + * write_to_file override reports through handleError; pushToolResult records a string result + * the same way so a later override cannot have its report dropped on the floor. + * + * @returns the error text the teardown reported, or undefined when it reported nothing + */ +async function reportedErrorFromParseFailureTeardown( + cline: Task, + toolCallId: string, + toolName: string, + errorMessage: string, +): Promise { + const tool = parseFailureTeardownTool(toolName) + if (!tool) { + return undefined + } + let reported: string | undefined + const callbacks: ToolCallbacks = { + askApproval: async () => false, + handleError: async (_action: string, error: Error) => void (reported = error.message), + pushToolResult: (content: ToolResponse) => (reported ??= typeof content === "string" ? content : undefined), + toolCallId, + } + await tool.onParameterParseFailure(cline, callbacks, new Error(errorMessage)) + return reported +} + /** * Processes and presents assistant message content to the user interface. * @@ -577,12 +623,26 @@ async function presentAssistantMessageBlock(cline: Task, policySnapshot: Request // Best-effort only } + // The call is dropped before dispatch, so the tool never sees it: the parse-failure + // boundary in BaseTool - write_to_file's only teardown for the partial ask, the abort + // listener, the streaming failure mark, and any diff preview a delta already opened - + // would not run either. Route the failure through that same boundary rather than + // writing a parallel cleanup here. When the teardown already surfaced the streaming + // error a delta captured, that is the error the user can act on, so it replaces the + // generic missing-nativeArgs text in the one tool_result below instead of being pushed + // as a second error for the same tool_use_id. + const teardownReport = await reportedErrorFromParseFailureTeardown( + cline, + toolCallId, + block.name, + errorMessage, + ) // Push tool_result directly without setting didAlreadyUseTool so streaming can // continue gracefully. cline.pushToolResultToUserContent({ type: "tool_result", tool_use_id: sanitizeToolUseId(toolCallId), - content: formatResponse.toolError(errorMessage), + content: formatResponse.toolError(teardownReport ?? errorMessage), is_error: true, }) diff --git a/src/core/task-persistence/__tests__/readFileWithMissingRetry.spec.ts b/src/core/task-persistence/__tests__/readFileWithMissingRetry.spec.ts index bf2a7a3dd6..7d2c9a8722 100644 --- a/src/core/task-persistence/__tests__/readFileWithMissingRetry.spec.ts +++ b/src/core/task-persistence/__tests__/readFileWithMissingRetry.spec.ts @@ -2,6 +2,7 @@ import * as fs from "fs/promises" import * as os from "os" import * as path from "path" +import * as recovery from "../../../utils/jsonFileRecovery" import { readFileWithMissingRetry } from "../readFileWithMissingRetry" describe("readFileWithMissingRetry", () => { @@ -26,4 +27,43 @@ describe("readFileWithMissingRetry", () => { it("propagates non-ENOENT errors", async () => { await expect(readFileWithMissingRetry(dir)).rejects.toMatchObject({ code: "EISDIR" }) }) + + // The callers of this reader classify the failure they receive by error code: + // apiMessages.ts maps ENOENT to "no file yet" and anything else to io_error, + // taskMessages.ts maps it to the "not_found" kind, and TaskHistoryStore.ts swallows + // it into null. A recovery that rejects must therefore not reach the caller as the + // read's error - the reader's own ENOENT is the failure those classifiers know. + it("reports the missing file, not the recovery failure, when recovery itself rejects", async () => { + const missing = path.join(dir, "api_mock_latest.json") + const recoveryError = Object.assign(new Error("recovery scan failed"), { code: "EBUSY" }) + // The recovery puts the file back and then fails - it loses the lock too late to + // report success. A rejection still cannot be read as "recovered": the reader cannot + // tell whether the recovery finished, and every caller classifies this read by error + // code. If the rejection counted as a recovery, the reader would return the planted + // bytes and the row below would pass on a third read. + const recoverySpy = vi.spyOn(recovery, "recoverMissingJsonFile").mockImplementation(async () => { + await fs.writeFile(missing, JSON.stringify({ recoveredBySomeoneElse: true })) + throw recoveryError + }) + try { + let failure: unknown + const value = await readFileWithMissingRetry(missing).catch((reason: unknown) => { + failure = reason + return undefined + }) + // The rejection carries EBUSY, which every caller above would report as an I/O + // error on a file that is simply not there yet; the reader's own failure is the + // ENOENT it already saw, and a resolved read of the planted bytes would be a third + // outcome neither the caller nor this row expects. + expect(failure).toBeDefined() + expect(value).toBeUndefined() + expect(failure).not.toBe(recoveryError) + expect(failure).toMatchObject({ code: "ENOENT" }) + // The recovery was attempted exactly once, so the missing-file retry the rows + // above assert is unchanged. + expect(recoverySpy).toHaveBeenCalledTimes(1) + } finally { + recoverySpy.mockRestore() + } + }) }) diff --git a/src/core/task-persistence/readFileWithMissingRetry.ts b/src/core/task-persistence/readFileWithMissingRetry.ts index 61edfcb3aa..03edbab4a2 100644 --- a/src/core/task-persistence/readFileWithMissingRetry.ts +++ b/src/core/task-persistence/readFileWithMissingRetry.ts @@ -46,7 +46,13 @@ export async function readFileWithMissingRetry(filePath: string): Promise false) + if (!recovered) throw retryError return fs.readFile(filePath, "utf8") } } diff --git a/src/core/task/Task.ts b/src/core/task/Task.ts index 77a1333b39..d1d3470ca5 100644 --- a/src/core/task/Task.ts +++ b/src/core/task/Task.ts @@ -3624,6 +3624,9 @@ export class Task extends EventEmitter implements TaskLike { // A host teardown never calls abortTask(): disposal has to raise the same // counter, or a write still parked on its path chain publishes after the // task is gone. + // Disposal drives the abort latch through the kernel, which sets abort and disposed + // together on disposeRequested in src/core/task/run-state/runState.ts, so this + // increment is what keeps a disposed task's queued writes out of a later run. this.cancellationGeneration++ this.driveRunEvent({ tag: "disposeRequested" }) } diff --git a/src/core/task/__tests__/Task.spec.ts b/src/core/task/__tests__/Task.spec.ts index 765dd1b2b6..2659fcef52 100644 --- a/src/core/task/__tests__/Task.spec.ts +++ b/src/core/task/__tests__/Task.spec.ts @@ -4851,6 +4851,38 @@ describe("Cline", () => { expect(task.cancellationGeneration).toBe(2) }) + it("advances the cancellation generation for the disposal an unmocked abort performs", async () => { + // The two rows above mock dispose(), so each proves one increment in isolation. The + // sequence the guarded-write fence actually sees is an abort that tears the task down: + // requestAbort raises the fence, and the dispose() that abortTaskOnce drives raises it + // again. Nothing is mocked here, so if either increment stopped landing - or if disposal + // stopped being part of an abort - this row reads the stale value. + const task = new Task({ + provider: mockProvider, + apiConfiguration: mockApiConfig, + task: "test task", + startTask: false, + }) + + expect(task.cancellationGeneration).toBe(0) + + // Started, not awaited. requestAbort is synchronous and raises the fence before any of the + // abort work runs (Task.abortTask calls it before it hands back abortPromise), so the increment + // has to be visible while the abort promise is still pending. Asserting the generation only + // after the await would still pass if the increment landed at the end of the teardown, which is + // exactly the delay that lets a write parked on its path chain publish after the task is gone. + const aborting = task.abortTask() + expect(task.cancellationGeneration).toBe(1) + + await aborting + + expect(task.abort).toBe(true) + // Disposal never marks a task abandoned; only an explicit abandon does. + expect(task.abandoned).toBe(false) + // One from requestAbort, one from the disposal the abort performed. + expect(task.cancellationGeneration).toBe(2) + }) + it("flushes pending state before TaskAborted and disposal while queue state is intact", async () => { const task = new Task({ provider: mockProvider, diff --git a/src/core/tools/BaseTool.ts b/src/core/tools/BaseTool.ts index 1e73a8285a..1c9aa0ab70 100644 --- a/src/core/tools/BaseTool.ts +++ b/src/core/tools/BaseTool.ts @@ -155,9 +155,23 @@ export abstract class BaseTool { throw new Error("Tool call is missing native arguments (nativeArgs).") } } catch (error) { - console.error(`Error parsing parameters:`, error) - const errorMessage = `Failed to parse ${this.name} parameters: ${error instanceof Error ? error.message : String(error)}` - await callbacks.handleError(`parsing ${this.name} args`, new Error(errorMessage)) + const parseError = error instanceof Error ? error : new Error(String(error)) + console.error(`Error parsing parameters:`, parseError) + // Final args could not be parsed (e.g. the model's tool call was truncated + // mid-JSON by the output token limit), so execute() will never run. If a + // streaming delta already opened a partial "tool" ask (partial: true), + // finalize it here or the webview spinner stays stuck indefinitely. + await task.finalizePartialToolAsk().catch((finalizeError) => { + console.error(`Error finalizing ${this.name} partial tool ask:`, finalizeError) + }) + // execute() never runs on this path, so tools that keep per-task state + // outside execute() (streaming failure marks, abort listeners) get their + // one remaining teardown boundary here. + const reportedStreamingFailure = await this.onParameterParseFailure(task, callbacks, parseError) + if (!reportedStreamingFailure) { + const errorMessage = `Failed to parse ${this.name} parameters: ${parseError.message}` + await callbacks.handleError(`parsing ${this.name} args`, new Error(errorMessage)) + } // Note: handleError already emits a tool_result via formatResponse.toolError in the caller. // Do NOT call pushToolResult here to avoid duplicate tool_result payloads. return @@ -166,4 +180,28 @@ export abstract class BaseTool { // Execute with typed parameters await this.execute(params, task, callbacks) } + + /** + * Teardown boundary for the native-argument parse-failure path in handle(). + * + * When nativeArgs are missing or malformed, execute() never runs, so per-task + * state a tool registered outside execute() (streaming failure marks, abort + * listeners) is never torn down there. Streaming tools override this to tear + * that state down and, when a streaming delta already failed, to report the + * captured streaming error instead of the generic parse error. + * + * The method is public on purpose: presentAssistantMessage() drops a complete known-tool + * block whose nativeArgs never parsed before the call reaches handle(), and it routes the + * failure through this same boundary so the teardown still runs for that call. The only + * override already declares the method without a visibility modifier. + * + * @param _task - Task instance + * @param _callbacks - Tool execution callbacks + * @param _parseError - The native-argument parse error + * @returns true when the override already reported the failure to the user, + * so handle() suppresses the generic parse error + */ + async onParameterParseFailure(_task: Task, _callbacks: ToolCallbacks, _parseError: Error): Promise { + return false + } } diff --git a/src/core/tools/ReadFileTool.ts b/src/core/tools/ReadFileTool.ts index e4e69b30ad..f80212eda8 100644 --- a/src/core/tools/ReadFileTool.ts +++ b/src/core/tools/ReadFileTool.ts @@ -17,13 +17,14 @@ import type { ReadFileParams, ReadFileMode, ReadFileToolParams, FileEntry, LineR import { isLegacyReadFileParams, type ClineSayTool } from "@roo-code/types" import { Task } from "../task/Task" +import { versionTokenOfStat } from "../../utils/versionToken" import { formatResponse } from "../prompts/responses" import { RecordSource } from "../context-tracking/FileContextTrackerTypes" import { isPathOutsideWorkspace } from "../../utils/pathUtils" import { getReadablePath } from "../../utils/path" import { extractTextFromFile, addLineNumbers, getSupportedBinaryFormats } from "../../integrations/misc/extract-text" import { readWithIndentation, readWithSlice } from "../../integrations/misc/indentation-reader" -import { DEFAULT_LINE_LIMIT } from "../prompts/tools/native-tools/read_file" +import { DEFAULT_LINE_LIMIT, MAX_LINE_LENGTH } from "../prompts/tools/native-tools/read_file" import type { ToolUse, PushToolResult } from "../../shared/tools" import { @@ -215,14 +216,49 @@ export class ReadFileTool extends BaseTool<"read_file"> { // Read text file content with lossy UTF-8 conversion // Reading as Buffer first allows graceful handling of non-UTF8 bytes // (they become U+FFFD replacement characters instead of throwing) + // A2 (epic #1375): capture the on-disk token before the read so a mutation + // landing mid-read is detected by the post-read stat below. + const preReadStats = await fs.stat(fullPath, { bigint: true }).catch(() => undefined) const buffer = await fs.readFile(fullPath) const fileContent = buffer.toString("utf-8") - const result = this.processTextFile(fileContent, entry) + // A lossy decode is not the whole file: the model never saw those bytes. + const lossyDecode = !Buffer.from(fileContent).equals(buffer) + // S4b follow-up (#46 / epic #1375): processTextFile reports whether the + // returned content is the whole file; the observation below records that + // scope so the write guard can deny full-file updates built on a partial view. + const processed = this.processTextFile(fileContent, entry) await task.fileContextTracker.trackFileContext(relPath, "read_tool" as RecordSource) + // A2 (plan #33 / epic #1375): record the observed on-disk version for the future write guard. + // The token is captured before AND after the read; the target is observed only + // when both match — a mutation between the two stats means the content the model + // received is not the on-disk state, and observing it would let a later write + // match a token the model never saw. A stat failure leaves the target + // unobserved and never fails the read. + // A task that was cancelled or disposed while this read was awaiting I/O must + // not record an observation: disposeOnce() has retired the registry, and the + // content this turn produced will never be acted on. Skipping also drops the + // post-read stat work for a task that no longer has a consumer. + if (!task.abort) { + const postReadStats = await fs.stat(fullPath, { bigint: true }).catch(() => undefined) + // Re-checked after the await: the guard above cannot see a cancellation + // that lands while the stat is in flight, and that read belongs to a run + // that will never act on it. + if (preReadStats && postReadStats && !task.abort) { + const preReadToken = versionTokenOfStat(preReadStats) + if (preReadToken === versionTokenOfStat(postReadStats)) { + task.observationRegistry.observe( + fullPath, + preReadToken, + processed.complete && !lossyDecode, + ) + } + } + } + updateFileResult(relPath, { - nativeContent: `File: ${relPath}\n${result}`, + nativeContent: `File: ${relPath}\n${processed.content}`, }) } catch (error) { const errorMsg = error instanceof Error ? error.message : String(error) @@ -266,8 +302,14 @@ export class ReadFileTool extends BaseTool<"read_file"> { /** * Process a text file according to the requested mode. + * + * Returns the content string plus whether that content is the complete + * file (S4b follow-up #46 / epic #1375): slice mode is complete only + * when it starts at line 1, returns every line, and was not truncated; + * indentation mode is never complete because it returns semantic blocks + * of the file, not the file itself. */ - private processTextFile(content: string, entry: InternalFileEntry): string { + private processTextFile(content: string, entry: InternalFileEntry): { content: string; complete: boolean } { const mode = entry.mode || "slice" if (mode === "indentation") { @@ -300,7 +342,15 @@ export class ReadFileTool extends BaseTool<"read_file"> { output += `\n\nIncluded ranges: ${rangeStr} (total: ${result.totalLines} lines)` } - return output + if (result.hasClippedLines) { + // A returned line can still be a partial view: clipping is reported + // separately from the omission notice, because the block may show + // every line it includes in truncated form. + output += `\nNote: Some lines in this view exceed ${MAX_LINE_LENGTH} characters and were clipped in this view.` + } + + // Indentation mode returns semantic blocks: never a complete file view. + return { content: output, complete: false } } // Slice mode (default): simple offset/limit reading @@ -323,11 +373,27 @@ export class ReadFileTool extends BaseTool<"read_file"> { To read more: Use the read_file tool with offset=${nextOffset} and limit=${limit}. ${result.content}` + if (result.hasClippedLines) { + // The slice cut lines off and also clipped long lines inside it, so both + // notices belong to the response. + output += `\nNote: Some lines in this view exceed ${MAX_LINE_LENGTH} characters and were clipped in this view.` + } + } else if (result.hasClippedLines) { + // Every line was returned, so there is no later offset to read: report the + // clipping without a next-offset hint, and keep the read incomplete so a + // full-file replacement cannot be built from a clipped line. + output = `IMPORTANT: Some lines exceed ${MAX_LINE_LENGTH} characters and were clipped in this view. ${offset1 === 1 ? "The file was read in full" : `The returned slice starts at line ${offset1} and reaches the end of the file`}, but the clipped lines were not shown in full.\n${result.content}` } else if (result.returnedLines === 0 && result.totalLines === 0) { output = "Note: File is empty" } - return output + // Complete only when the slice starts at line 1, returned every line, and + // showed every line in full (returnedLines === totalLines follows from the + // first two conditions): a partial start, a truncated tail, or a clipped + // line means the model did not see the whole file. + const complete = offset0 === 0 && !result.wasTruncated && !result.hasClippedLines + + return { content: output, complete } } /** @@ -770,9 +836,20 @@ export class ReadFileTool extends BaseTool<"read_file"> { } // Read text file - const rawContent = await fs.readFile(fullPath, "utf8") + // A2 (epic #1375): capture the on-disk token before the read so a mutation + // landing mid-read is detected by the post-read stat below. + const preReadStats = await fs.stat(fullPath, { bigint: true }).catch(() => undefined) + const rawBuffer = await fs.readFile(fullPath) + const rawContent = rawBuffer.toString("utf-8") + // Same contract: a lossy decode is a partial view. + const lossyDecode = !Buffer.from(rawContent).equals(rawBuffer) // Handle line ranges if specified + // S4b follow-up (#46 / epic #1375): a line-range read returns only the requested + // ranges, and a slice truncated to DEFAULT_LINE_LIMIT returns only the head of + // the file — record such observations as partial so the write guard denies a + // full-file update built on them. + let readComplete = false let content: string if (entry.lineRanges && entry.lineRanges.length > 0) { const lines = rawContent.split("\n") @@ -792,8 +869,16 @@ export class ReadFileTool extends BaseTool<"read_file"> { // Read with default limits using slice mode const result = readWithSlice(rawContent, 0, DEFAULT_LINE_LIMIT) content = result.content + readComplete = !result.wasTruncated && !result.hasClippedLines if (result.wasTruncated) { content += `\n\n[File truncated: showing ${result.returnedLines} of ${result.totalLines} total lines]` + if (result.hasClippedLines) { + // Both notices: the slice was truncated and a line inside it was + // clipped. + content += `\n\n[Some lines exceed the per-line length cap and were clipped in this view]` + } + } else if (result.hasClippedLines) { + content += `\n\n[Some lines exceed the per-line length cap and were clipped in this view]` } } @@ -801,6 +886,24 @@ export class ReadFileTool extends BaseTool<"read_file"> { // Track file in context await task.fileContextTracker.trackFileContext(relPath, "read_tool") + + // A2 (plan #33 / epic #1375): mirror the native path — record the observed + // on-disk version so legacy-format reads also feed the future write guard. + // Observe only when the pre-read and post-read tokens match (a mutation between + // them means the returned content is not the on-disk state). A stat failure + // leaves the target unobserved and never fails the read. + // Same contract as the native path: an aborted or disposed task records nothing. + if (!task.abort) { + const postReadStats = await fs.stat(fullPath, { bigint: true }).catch(() => undefined) + // Re-checked after the await, as on the native path: a cancel landing + // during the stat must still record nothing. + if (preReadStats && postReadStats && !task.abort) { + const preReadToken = versionTokenOfStat(preReadStats) + if (preReadToken === versionTokenOfStat(postReadStats)) { + task.observationRegistry.observe(fullPath, preReadToken, readComplete && !lossyDecode) + } + } + } } catch (error) { const errorMsg = error instanceof Error ? error.message : String(error) results.push(`File: ${relPath}\nError: ${errorMsg}`) diff --git a/src/core/tools/WriteToFileTool.ts b/src/core/tools/WriteToFileTool.ts index 0c5c80abb9..c747d87f51 100644 --- a/src/core/tools/WriteToFileTool.ts +++ b/src/core/tools/WriteToFileTool.ts @@ -1,7 +1,7 @@ import path from "path" import fs from "fs/promises" -import { type ClineSayTool, DEFAULT_WRITE_DELAY_MS } from "@roo-code/types" +import { type ClineSayTool, DEFAULT_WRITE_DELAY_MS, RooCodeEventName } from "@roo-code/types" import { Task } from "../task/Task" import { formatResponse } from "../prompts/responses" @@ -22,9 +22,350 @@ interface WriteToFileParams { content: string } +/** + * Per-task partial-streaming state tracked by WriteToFileTool. + */ +interface TaskPartialStreamState { + /** Last path seen during streaming; undefined until the first delta. */ + lastSeenPartialPath: string | undefined + /** True once this stream was found to be editing a different path than the retained session. */ + differentPathStream: boolean + /** True once this stream has reached the diff view (open/update below), i.e. once it owns + * the preview and artifacts a teardown here would restore. */ + ownsPreview: boolean + /** True once a streaming delta hit a fatal filesystem error. */ + streamFailed: boolean + /** The original filesystem error of the failed streaming delta, reported once + * by onParameterParseFailure() when the final block fails to parse (so + * execute() never runs and would never report it). */ + streamError: Error | undefined + /** The task that owns this state; target for abort-listener deregistration. */ + task: Task + /** TaskAborted listener that tears this state down; registered once per task. */ + abortCleanup: () => void +} + export class WriteToFileTool extends BaseTool<"write_to_file"> { readonly name = "write_to_file" as const + /** + * Per-task partial-streaming state, keyed by task id (taskId + instanceId). + * + * All per-task fields live in one object per task so that resetTaskPartialState() / + * resetPartialState() cannot clear a subset of them and leak the rest (abort + * listener, failure mark, path-stabilization entry) for an abandoned stream. + * + * This deliberately diverges from the sibling streaming tools (ApplyDiffTool, + * EditFileTool, SearchReplaceTool, EditTool), which rely on BaseTool's singleton + * lastSeenPartialPath / resetPartialState and keep no failure state. The divergence is + * intentional, for two reasons: + * + * 1. Only this tool's handlePartial performs failure-prone streaming work + * (diffViewProvider.open/update, which can throw EACCES/EROFS); the siblings only + * send a task.ask preview. Without per-task failure tracking, every later delta for + * a failed path would re-attempt the failing operation and re-spawn a partial tool + * message. + * + * 2. The tool instance is a module-level singleton shared by every task, including + * tasks from different ClineProvider instances (e.g. sidebar and tab-panel + * providers, which activate independently). A single provider streams at most one + * task at a time — TaskScheduler gates task.run() at maxConcurrency=1 and + * delegation disposes the parent before the child starts — so per-task keying is + * reachable specifically across providers, where two providers can stream + * write_to_file concurrently through this same singleton. + * + * Lifting this per-task keying into BaseTool for all streaming tools is a follow-up + * (separate PR); it is deliberately not done here. + */ + private taskPartialStreamState = new Map() + + private getPartialStreamFailureKey(task: Task): string { + return `${task.taskId}.${task.instanceId}` + } + + /** + * Whether this task's stream is the one that reached the diff view. Only that stream may tear the + * view down: a stream whose path never stabilized, or that was found to belong to a different + * path than the retained session, never opened or updated the view, so discarding or resetting + * there would throw away a session it does not own - the same hazard the different-path + * rejection in execute() guards, one level earlier. + */ + private streamOwnsPreview(task: Task): boolean { + return this.taskPartialStreamState.get(this.getPartialStreamFailureKey(task))?.ownsPreview === true + } + + /** + * Get this task's partial stream state, creating it on first use and registering the + * TaskAborted teardown listener exactly once per task. + */ + private getTaskPartialStreamState(task: Task): TaskPartialStreamState { + const key = this.getPartialStreamFailureKey(task) + const existing = this.taskPartialStreamState.get(key) + if (existing) { + return existing + } + + const state: TaskPartialStreamState = { + lastSeenPartialPath: undefined, + differentPathStream: false, + ownsPreview: false, + streamFailed: false, + streamError: undefined, + task, + abortCleanup: () => this.resetTaskPartialState(task), + } + this.taskPartialStreamState.set(key, state) + task.once(RooCodeEventName.TaskAborted, state.abortCleanup) + return state + } + + private hasPathStabilizedForTask(state: TaskPartialStreamState, partialPath: string | undefined): boolean { + const pathHasStabilized = state.lastSeenPartialPath !== undefined && state.lastSeenPartialPath === partialPath + state.lastSeenPartialPath = partialPath + return pathHasStabilized && !!partialPath + } + + /** + * Clear a task's partial-stream state from a disposal path that does not abort first. + * Task.dispose() removes every listener, so a task disposed directly (for example + * ClineProvider.cleanupFailedHistoryTask()) never fires the TaskAborted cleanup and + * this singleton would keep the disposed task and its diff-view provider. + */ + public clearTaskState(task: Task): void { + this.resetTaskPartialState(task) + } + + private resetTaskPartialState(task: Task): void { + const key = this.getPartialStreamFailureKey(task) + const state = this.taskPartialStreamState.get(key) + if (!state) { + return + } + state.task.off(RooCodeEventName.TaskAborted, state.abortCleanup) + this.taskPartialStreamState.delete(key) + } + + /** + * Whether this task's partial stream is still the live one. handlePartial() awaits provider + * state, a filesystem probe, task.ask() and the diff view's open() before it streams content; + * a cancellation during any of those awaits runs the TaskAborted teardown (or a direct + * clearTaskState), which deletes this entry. Continuing would re-ask and re-open a diff view + * for a task the user already cancelled, resurrecting the state the teardown released. + * Identity, not presence: an entry re-created under the same key belongs to a new stream, + * and this delta must not write into it. + */ + private isPartialStreamStillLive(task: Task, state: TaskPartialStreamState): boolean { + return this.taskPartialStreamState.get(this.getPartialStreamFailureKey(task)) === state + } + + private async resetDiffViewAfterWrite(task: Task): Promise { + await task.diffViewProvider.reset().catch((resetError) => { + console.error("Error resetting write_to_file diff view:", resetError) + }) + } + + /** + * Release the diff view of a write that was never approved, then let the caller reset it. + * + * reset() clears the provider's state but leaves the diff document dirty with the + * streamed content; a user save would then persist a write the task never completed + * (denied or failed before approval). Must run BEFORE resetDiffViewAfterWrite(), + * since reset() clears the state the discard relies on. No-op when no diff view + * is open. Failures are logged and reported through the return value: the caller + * must not treat the teardown as complete when this returns false, because the + * document may still hold the unapproved content, but the remaining cleanup (reset, + * per-task state teardown) still runs so the task is not left half-torn-down. + * + * This is deliberately not revertChanges(): that method SAVES. For a new file it writes + * the streamed partial output into the placeholder before deleting it, and for an + * existing file it writes the restored original back to a file this stream never + * changed. discardUnapprovedStream() empties or restores the buffer in memory and + * closes the tab only once it is clean, so nothing the user did not approve reaches + * disk and the modified side of the vscode.diff tab - a TabInputTextDiff, which + * discardFileTab() cannot see - is what actually gets discarded. + */ + private async discardUnapprovedStreamBeforeReset(task: Task): Promise { + try { + await task.diffViewProvider.discardUnapprovedStream() + return true + } catch (discardError) { + console.error("Error discarding the unapproved write_to_file diff view:", discardError) + return false + } + } + + /** + * Cleanup for an approved write whose saveChanges() failed before its commit point: + * approval is not persistence - nothing landed, so the placeholder open() created is + * still the empty file on disk and still owned. Remove it before reset() forgets the + * ownership, or the empty file is stranded unowned: a later attempt would treat it as + * the pre-existing target and a later denial's rollback would no longer delete it. + * The dirty editor keeps the approved content for a manual save or retry. A removal + * that fails (EPERM, EACCES) must not be swallowed: ownership is preserved (the + * provider keeps placeholderPath when the unlink rejects) and the caller must skip + * reset() - clearing the session would strand the placeholder unowned with no retry + * path - and report the hazard instead. Returns whether the placeholder was removed. + */ + private async discardOwnedPlaceholderBeforeReset(task: Task): Promise { + try { + await task.diffViewProvider.discardOwnedPlaceholder() + return true + } catch (placeholderError) { + console.error("Error removing the uncommitted write_to_file placeholder:", placeholderError) + return false + } + } + + /** + * Surface a placeholder this edit still owns but could not remove. Like the rollback + * report, the hazard has to be visible in the chat: the empty file is still on disk, + * still owned, and the diff session was left open for a retry instead of being reset. + * A failing say must not abort the teardown, so its failure is logged only. + */ + private async reportPlaceholderStranded(task: Task): Promise { + await task + .say( + "error", + "write_to_file: the placeholder created for this new file could not be removed after the failed write, so this edit still owns it and the diff session was left open for a retry instead of being reset.", + ) + .catch((sayError) => { + console.error("Error reporting write_to_file stranded placeholder failure:", sayError) + }) + } + + private async finalizePartialToolAskAfterFailure(task: Task, text?: string): Promise { + await task.finalizePartialToolAsk(text).catch((finalizeError) => { + console.error("Error finalizing write_to_file partial tool ask:", finalizeError) + }) + } + + /** + * Surface a failed rollback to the user. The hazard has to be visible in the chat, + * not only in the console: the editor may still hold content the task never + * approved and a save of it would land an unauthorized write. A failing say must + * not abort the teardown - a retained streaming error still has to reach the user + * through handleError - so its failure is logged only, matching the other cleanup + * helpers in this file. + */ + private async reportRevertFailure(task: Task): Promise { + await task + .say( + "error", + "write_to_file: the diff editor could not be restored after the failed tool call, so it may still show unapproved content. Do not save that editor.", + ) + .catch((sayError) => { + console.error("Error reporting write_to_file rollback failure:", sayError) + }) + } + + /** + * Cleanup for a failed partial stream: restore the diff document, close the view, + * and - when the restore itself failed - tell the user the editor may still hold + * unapproved content, the same way the parse-failure teardown does. Without the + * report, a failed rollback here is invisible: the stream error that triggered the + * cleanup is a different failure and is reported elsewhere. + */ + private async cleanupFailedPartialStream(task: Task): Promise { + const reverted = await this.discardUnapprovedStreamBeforeReset(task) + // A restore that failed leaves the buffer holding content this task never approved, + // and the open diff session (isEditing + relPath) is what tells a later call that + // this path still owes a rollback. reset() would clear that session and leave the + // unapproved content one save away from disk with nobody left to roll it back, and + // when the failed restore also still owns the placeholder, reset() would forget that + // ownership and strand the empty file unowned. So the view is reset only once the + // restore actually landed; otherwise the hazard is reported instead - the same + // discipline execute() uses on its error path. + const strandedPlaceholder = !reverted && task.diffViewProvider.ownsPlaceholder + if (reverted) { + await this.resetDiffViewAfterWrite(task) + } + if (!reverted) { + await this.reportRevertFailure(task) + } + if (strandedPlaceholder) { + await this.reportPlaceholderStranded(task) + } + } + + /** + * Teardown boundary for the handle() parse-failure path, where execute() never + * runs and therefore its finally (resetTaskPartialState) never runs either. + * + * Tears down the per-task stream state: otherwise the abort listener leaks for + * the task's lifetime, and when a streaming delta had failed, the streamFailed + * guard would suppress the diff preview of every later write_to_file in this + * task. Restores the diff document: streaming may have opened it with + * unapproved partial content, and execute()'s error cleanup (revert + reset) + * never fires on this path, so a user save could persist the content without + * the teardown here. When a streaming delta already hit a fatal filesystem + * error, that error is what the user can act on, so report it with the same + * "writing file" context execute()'s catch uses, and suppress the incidental + * parse error. + */ + override async onParameterParseFailure(task: Task, callbacks: ToolCallbacks, parseError: Error): Promise { + const state = this.taskPartialStreamState.get(this.getPartialStreamFailureKey(task)) + if (!state) { + return false + } + if (state.differentPathStream || !state.ownsPreview) { + // This stream never owned the diff session: either it carries another path's retained, + // approved edit, or its own path never stabilized enough to reach the view. Discarding or + // resetting the view here would throw that session away, so only release this stream's + // own bookkeeping and report any streaming failure. + this.resetTaskPartialState(task) + if (!state.streamError) { + return false + } + void parseError + await callbacks.handleError("writing file", state.streamError) + return true + } + // Streaming may have opened the diff view with unapproved partial content. + // execute() never runs on this path, so its error cleanup (revert + reset) + // never fires: restore the document here so a user save cannot persist + // content the write never completed (the same invariant the denial and + // streaming-failure paths maintain). Both helpers no-op when no view is open. + // The revert runs BEFORE the per-task state is torn down: when it fails, the + // document can still hold that unapproved content, and the recovery state has + // to exist while the outcome is decided and reported. + const reverted = await this.discardUnapprovedStreamBeforeReset(task) + // The same rule as the failed-stream cleanup: tear the recovery state down only + // once the restore landed. When it failed, the buffer can still hold unapproved + // content, and this stream's entry (with its abort listener) together with the open + // diff session are what let a later write for the same path, or an approval, finish + // the teardown instead of leaving the content with no owner. + if (reverted) { + this.resetTaskPartialState(task) + await this.resetDiffViewAfterWrite(task) + } + // The same ownership guard as execute(): a rollback that could not remove the + // placeholder leaves it owned, and reset() would strand it unowned. + const strandedPlaceholder = !reverted && task.diffViewProvider.ownsPlaceholder + if (!reverted) { + // Do not report a completed teardown: the editor may still show content this + // task never approved, and saving it would land a write the user never + // authorized. The user has to be able to tell that from the UI. + await this.reportRevertFailure(task) + } + if (strandedPlaceholder) { + await this.reportPlaceholderStranded(task) + } + if (!state.streamError) { + return false + } + void parseError + await callbacks.handleError("writing file", state.streamError) + return true + } + + override resetPartialState(): void { + super.resetPartialState() + for (const state of this.taskPartialStreamState.values()) { + state.task.off(RooCodeEventName.TaskAborted, state.abortCleanup) + } + this.taskPartialStreamState.clear() + } + async execute(params: WriteToFileParams, task: Task, callbacks: ToolCallbacks): Promise { const { pushToolResult, handleError, askApproval } = callbacks const relPath = params.path @@ -34,7 +375,17 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { task.consecutiveMistakeCount++ task.recordToolError("write_to_file") pushToolResult(await task.sayAndCreateMissingParamError("write_to_file", "path")) - await task.diffViewProvider.reset() + // Returning here skips the cleanup below: release THIS task's stream state (and only this + // task's) so the abort listener and any streamFailed guard do not outlive the call, and + // tear down the diff view an earlier streaming delta may have opened - otherwise its + // unapproved content sits in the editor until the next write. Only the stream that reached + // the view may do that teardown: a never-stabilized path never touched it, and a retained + // session may belong to another path's approved edit. + const ownsPreview = this.streamOwnsPreview(task) + this.resetTaskPartialState(task) + if (ownsPreview) { + await this.cleanupFailedPartialStream(task) + } return } @@ -42,7 +393,41 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { task.consecutiveMistakeCount++ task.recordToolError("write_to_file") pushToolResult(await task.sayAndCreateMissingParamError("write_to_file", "content")) - await task.diffViewProvider.reset() + + // Returning here skips the cleanup below: release THIS task's stream state (and only this + // task's) so the abort listener and any streamFailed guard do not outlive the call. The + // teardown belongs to the stream that reached the diff view: a call whose path never + // stabilized never touched the view, and discarding or resetting then would throw away a + // retained session that belongs to another path. + const ownsPreview = this.streamOwnsPreview(task) + this.resetTaskPartialState(task) + if (ownsPreview) { + await this.cleanupFailedPartialStream(task) + } + return + } + + // A retained session belongs to ITS path: when a rollback could not complete, + // the provider keeps the dirty buffer and relPath so the user's content survives + // a retry. Writing a DIFFERENT path through that session would update and save + // the old document while asking approval for the new one, so the write is + // rejected before any cleanup path can reset the retained session. + if (task.diffViewProvider.isEditingDifferentPath(relPath)) { + task.consecutiveMistakeCount++ + task.recordToolError("write_to_file") + const retainedPath = task.diffViewProvider.editingRelPath ?? "another file" + // The retained session is only released by a retry of ITS path (which reuses the + // session and reaches reset()) - saving or closing the editor does not clear + // isEditing/relPath in this process, so that remedy would loop. + const retainedErrorMessage = + `Cannot write '${relPath}': an unfinished write to '${retainedPath}' must be resolved first. ` + + `Retry the write to '${retainedPath}' to reuse and finish that session, then retry this write.` + await task.say("error", retainedErrorMessage) + pushToolResult(formatResponse.toolError(retainedErrorMessage)) + // This return skips the try/finally below, so the per-task stream state a delta may + // have created for the rejected path must be released here: otherwise its TaskAborted + // listener leaks and a streamFailed flag would suppress every later write_to_file delta. + this.resetTaskPartialState(task) return } @@ -51,11 +436,26 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { if (!accessAllowed) { await task.say("rooignore_error", relPath) pushToolResult(formatResponse.rooIgnoreError(relPath)) + + // Returning here skips the cleanup below: release THIS task's stream state (and + // only this task's) so the abort listener and any streamFailed guard do not outlive + // the call. The denial can arrive after a streaming delta opened the denied path and + // streamed unapproved content into it, so the diff view is torn down here too - the + // write never happens, and a later save of that editor would land it anyway. + this.resetTaskPartialState(task) + await this.cleanupFailedPartialStream(task) return } const isWriteProtected = task.rooProtectedController?.isWriteProtected(relPath) || false + // The point of no return for this write. saveChanges() persists the document and then keeps + // working (closing the diff views, tab bookkeeping, diagnostics), and trackFileContext() and + // pushToolWriteResult() run after it, so a rejection past this point must not roll back a + // write the user already approved: the rollback would restore the previous content, or delete + // a file that was created and saved. Set only once the durable write has landed. + let writeCommitted = false + let fileExists: boolean const absolutePath = path.resolve(task.cwd, relPath) @@ -66,12 +466,6 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { task.diffViewProvider.editType = fileExists ? "modify" : "create" } - // Create parent directories early for new files to prevent ENOENT errors - // in subsequent operations (e.g., diffViewProvider.open, fs.readFile) - if (!fileExists) { - await createDirectoriesForFile(absolutePath) - } - if (newContent.startsWith("```")) { newContent = newContent.split("\n").slice(1).join("\n") } @@ -95,7 +489,19 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { isProtected: isWriteProtected, } + // Tracks whether the user approved the write, so the error path only reverts the + // diff document when the content was never approved (an approved edit is kept in + // the editor so the user can save it manually after a late failure). + let writeApproved = false + try { + // Create parent directories for new files inside the try block so filesystem + // errors (EROFS, EACCES, etc.) route through handleError with proper cleanup + // and consecutive-mistake counting, rather than escaping unhandled. + if (!fileExists) { + await createDirectoriesForFile(absolutePath) + } + task.consecutiveMistakeCount = 0 const provider = task.providerRef.deref() @@ -129,10 +535,31 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { const didApprove = await askApproval("tool", completeMessage, undefined, isWriteProtected) if (!didApprove) { + // The prevent-focus branch set editType/originalContent on the provider + // before asking. Clear them on denial (no diff document was opened in + // this branch, so reset() is sufficient; the non-prevent-focus denial + // branch resets through revertChanges()), so a later write re-checks + // the file system instead of reusing the stale editType. + await this.resetDiffViewAfterWrite(task) return } - - await task.diffViewProvider.saveDirectly(relPath, newContent, false, diagnosticsEnabled, writeDelayMs) + writeApproved = true + + // saveDirectly() performs the write itself, so it is the only place that can say when the + // content landed. The flag is set there, at the filesystem write, and not when the call + // returns: the document open, the forced save and the diagnostics that follow can still + // reject, and by then the content the user approved is already on disk, which is where the + // rollback below has to stand down from. + await task.diffViewProvider.saveDirectly( + relPath, + newContent, + false, + diagnosticsEnabled, + writeDelayMs, + () => { + writeCommitted = true + }, + ) } else { if (!task.diffViewProvider.isEditing) { const partialMessage = JSON.stringify(sharedMessageProps) @@ -164,7 +591,14 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { return } - await task.diffViewProvider.saveChanges(diagnosticsEnabled, writeDelayMs) + writeApproved = true + + await task.diffViewProvider.saveChanges(diagnosticsEnabled, writeDelayMs, () => { + // Signalled by saveChanges() at the document save, not when it returns: the editor + // bookkeeping and diagnostics that follow can still reject, and by then the file has + // already landed. + writeCommitted = true + }) } if (relPath) { @@ -177,17 +611,61 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { pushToolResult(message) - await task.diffViewProvider.reset() - this.resetPartialState() + await this.resetDiffViewAfterWrite(task) task.processQueuedMessages() return } catch (error) { - await handleError("writing file", error as Error) - await task.diffViewProvider.reset() - this.resetPartialState() + // Finalize any open partial tool message so the UI spinner doesn't get stuck. + // The partial ask fired during streaming (handlePartial) or early in execute sets + // partial: true on the webview message; without this, the spinner persists even + // after the error bubble appears. + await this.finalizePartialToolAskAfterFailure(task) + // The diff cleanup runs in a finally around handleError: the production + // handleError awaits Task.say(), which rejects when the task is aborted, and a + // rejected handleError must not skip restoring the unapproved streamed content. + try { + await handleError("writing file", error as Error) + } finally { + // Before approval the diff document holds unapproved streamed content: + // restore it so a user save cannot persist it. After approval the content + // is the user's accepted edit -- keep it in the editor (dirty) so they can + // save it manually. + let reverted = true + let strandedPlaceholder = false + // Two independent stand-downs: the user approved this content, or the write is already + // durable. Either one makes a rollback undo something the user wanted rather than + // cleaning up this call's debris. + if (!writeApproved && !writeCommitted) { + reverted = await this.discardUnapprovedStreamBeforeReset(task) + // A denial whose rollback could not remove the placeholder (refused restore, + // EPERM unlink) leaves it owned: reset() would forget that ownership and + // strand the empty file unowned, so it is skipped and the hazard reported - + // the same discipline as the pre-commit save-failure path below. + strandedPlaceholder = !reverted && task.diffViewProvider.ownsPlaceholder + } else if (writeApproved && !writeCommitted) { + // saveChanges() failed before its commit point: the write never persisted, + // so the owned empty placeholder must not be stranded unowned by reset(). + strandedPlaceholder = !(await this.discardOwnedPlaceholderBeforeReset(task)) + } + if (!strandedPlaceholder) { + await this.resetDiffViewAfterWrite(task) + } + if (!reverted) { + // The restore failed, so the editor still holds content this task never approved. + // The error the user sees on this path is the write failure, not this one. + await this.reportRevertFailure(task) + } + if (strandedPlaceholder) { + // The placeholder is still on disk and still owned; reset() was skipped so + // the session keeps that ownership for a retry. Make the hazard visible. + await this.reportPlaceholderStranded(task) + } + } return + } finally { + this.resetTaskPartialState(task) } } @@ -195,62 +673,188 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> { const relPath: string | undefined = block.params.path const newContent: string | undefined = block.params.content - // Wait for path to stabilize before showing UI (prevents truncated paths) - if (!this.hasPathStabilized(relPath) || newContent === undefined) { + const partialStreamFailureKey = this.getPartialStreamFailureKey(task) + + // A prior streaming delta for this task already hit a fatal filesystem error. + // Skip further streaming work so we don't create a new partial tool message on every + // subsequent delta. execute() will report the error once when the block completes. + if (this.taskPartialStreamState.get(partialStreamFailureKey)?.streamFailed) { return } - const provider = task.providerRef.deref() - const state = await provider?.getState() - const isPreventFocusDisruptionEnabled = experiments.isEnabled( - state?.experiments ?? {}, - EXPERIMENT_IDS.PREVENT_FOCUS_DISRUPTION, - ) + // Get (or create) this task's state; registers the TaskAborted teardown listener + // once, so abandoned streams are torn down even if execute() never runs. + const partialStreamState = this.getTaskPartialStreamState(task) - if (isPreventFocusDisruptionEnabled) { + // Wait for path to stabilize before showing UI (prevents truncated paths) + if (!this.hasPathStabilizedForTask(partialStreamState, relPath) || newContent === undefined) { return } - // relPath is guaranteed non-null after hasPathStabilized - let fileExists: boolean - const absolutePath = path.resolve(task.cwd, relPath!) + // Everything below runs after getTaskPartialStreamState() registered this task's entry and its + // TaskAborted listener, so it belongs inside a boundary that releases them. The awaits here look + // like reads and are not: provider.getState() is an await into the extension host and the + // filesystem probe can reject. If either does, this delta reaches neither the streaming block + // nor execute()'s teardown, and BaseTool.handle() only reports the error - which would leave + // the singleton holding a task that nothing else ever releases. - if (task.diffViewProvider.editType !== undefined) { - fileExists = task.diffViewProvider.editType === "modify" - } else { - fileExists = await fileExistsAtPath(absolutePath) - task.diffViewProvider.editType = fileExists ? "modify" : "create" - } + // Declared outside the try: the streaming catch below reads it, and a try block's + // own scope is not visible to code that runs after the try. + let partialMessage: string | undefined - // Create parent directories early for new files to prevent ENOENT errors - // in subsequent operations (e.g., diffViewProvider.open) - if (!fileExists) { - await createDirectoriesForFile(absolutePath) - } + try { + const provider = task.providerRef.deref() + const state = await provider?.getState() + // Cancelled while provider state was in flight: the teardown already released this + // task's stream state, so this delta must not go on to ask or open a diff view. + if (!this.isPartialStreamStillLive(task, partialStreamState)) { + return + } - const isWriteProtected = task.rooProtectedController?.isWriteProtected(relPath!) || false - const isOutsideWorkspace = isPathOutsideWorkspace(absolutePath) + const isPreventFocusDisruptionEnabled = experiments.isEnabled( + state?.experiments ?? {}, + EXPERIMENT_IDS.PREVENT_FOCUS_DISRUPTION, + ) - const sharedMessageProps: ClineSayTool = { - tool: fileExists ? "editedExistingFile" : "newFileCreated", - path: getReadablePath(task.cwd, relPath!), - content: newContent || "", - isOutsideWorkspace, - isProtected: isWriteProtected, - } + if (isPreventFocusDisruptionEnabled) { + // The preview is suppressed for this stream: release the entry registered above so the + // abort listener and any failure mark do not outlive a delta that never shows a diff + // view and never reaches execute()'s teardown. + super.resetPartialState() + this.resetTaskPartialState(task) + return + } - const partialMessage = JSON.stringify(sharedMessageProps) - await task.ask("tool", partialMessage, block.partial).catch(() => {}) + // relPath is guaranteed non-null after hasPathStabilized + let fileExists: boolean + const absolutePath = path.resolve(task.cwd, relPath!) - if (newContent) { - if (!task.diffViewProvider.isEditing) { - await task.diffViewProvider.open(relPath!) + if (task.diffViewProvider.editType !== undefined) { + fileExists = task.diffViewProvider.editType === "modify" + } else { + fileExists = await fileExistsAtPath(absolutePath) + task.diffViewProvider.editType = fileExists ? "modify" : "create" } - await task.diffViewProvider.update( - everyLineHasLineNumbers(newContent) ? stripLineNumbers(newContent) : newContent, - false, - ) + // Cancelled during the filesystem probe: stop before the partial ask and the diff view. + // (The probe above is the only await in this branch.) + if (!this.isPartialStreamStillLive(task, partialStreamState)) { + return + } + + const isWriteProtected = task.rooProtectedController?.isWriteProtected(relPath!) || false + const isOutsideWorkspace = isPathOutsideWorkspace(absolutePath) + + const sharedMessageProps: ClineSayTool = { + tool: fileExists ? "editedExistingFile" : "newFileCreated", + path: getReadablePath(task.cwd, relPath!), + content: newContent || "", + isOutsideWorkspace, + isProtected: isWriteProtected, + } + + // A retained session belongs to its own path: streaming a different path's deltas + // must not open a partial ask (the final rejection in execute() does not finalize it, + // leaving a spinner) and must not touch the diff view. Remember the stream so a + // later parse failure does not discard the retained, approved session. + if (task.diffViewProvider.isEditingDifferentPath(relPath!)) { + partialStreamState.differentPathStream = true + return + } + + partialMessage = JSON.stringify(sharedMessageProps) + await task.ask("tool", partialMessage, block.partial).catch(() => {}) + + // Cancelled while the partial ask was in flight: the teardown released this task's + // state, so this delta must not touch the diff view. + if (!this.isPartialStreamStillLive(task, partialStreamState)) { + return + } + } catch (error) { + // Unexpected failure in the pre-streaming window: nothing was streamed and nothing was shown, + // so this is not the retained-streaming-failure case the inner catch below keeps state for. + // Release this delta's entry and its listener before the error reaches BaseTool.handle(), + // then rethrow so the delta is still reported. Identity-guarded: if a cancellation already + // released the entry and a newer stream re-created it under the same key, that entry stays. + // An earlier delta of THIS stream may already have filled the view with unapproved content, + // in which case the discard has to run before the entry goes: afterwards nothing else in this + // path can restore that preview. A stream that never reached the view leaves any session + // (its own or another path's) exactly as it found it. + if (this.isPartialStreamStillLive(task, partialStreamState)) { + if (partialStreamState.ownsPreview) { + await this.cleanupFailedPartialStream(task) + } + this.resetTaskPartialState(task) + } + throw error + } + + if (newContent) { + // From here this delta is committed to the diff view: the open() and update() below are what + // put unapproved partial content into it, so this stream - not a later call - owns whatever the + // view and the created artifacts hold. Every teardown site below gates on that ownership. + partialStreamState.ownsPreview = true + try { + if (!task.diffViewProvider.isEditing) { + await task.diffViewProvider.open(relPath!) + } + + // Cancelled while open() was in flight: do not stream partial content into a + // cancelled task's view. + if (!this.isPartialStreamStillLive(task, partialStreamState)) { + // The cancellation teardown ran while open() was still pending, so it could only + // release what existed at that moment. open() then finished: it created the + // directories and the empty placeholder and set isEditing + relPath on the + // provider. This entry is already gone, so nothing else owns those artifacts - + // they would sit there until a later write to the same path found a session this + // task never opened. Release what the late open completed before returning. + await this.cleanupFailedPartialStream(task) + return + } + + await task.diffViewProvider.update( + everyLineHasLineNumbers(newContent) ? stripLineNumbers(newContent) : newContent, + false, + ) + } catch (error) { + // The task may have been aborted while open() or update() was in flight. The teardown + // already released this entry and the disposal path already owns the diff cleanup, so + // marking, finalizing and restoring here would be a second cleanup of the same stream: + // a second partial-tool row and a second restore racing the first. + if (!this.isPartialStreamStillLive(task, partialStreamState)) { + return + } + + // Opening or updating the diff view can throw on filesystem errors + // (EACCES/EROFS on read-only paths). Finalize the partial tool message + // so the UI spinner doesn't get stuck and reset the diff view. Do NOT + // rethrow: the same filesystem operation is retried in execute() once the + // block completes, and that authoritative non-partial path reports the + // error to the user. Surfacing it here too would show the same error twice. + // Swallowing it here is safe because the agent loop advances naturally when + // the non-partial block arrives (it does not depend on this throw). + console.error(`Error streaming write_to_file diff view:`, error) + // Mark the stream as failed so later deltas don't re-attempt and spawn a new + // partial tool message each time. Retain the original error: if the final + // block later fails to parse, execute() never runs and only + // onParameterParseFailure() can report this failure to the user. + partialStreamState.streamFailed = true + partialStreamState.streamError = error instanceof Error ? error : new Error(String(error)) + await this.finalizePartialToolAskAfterFailure(task, partialMessage) + + // Finalizing is an await: a cancellation during it has already run the teardown and the + // disposal cleanup, so the restore below must not run a second time over the same view. + if (!this.isPartialStreamStillLive(task, partialStreamState)) { + return + } + + // The write was never approved: restore the document so a user save cannot + // persist the failed streamed content (reset() alone leaves it dirty), and + // surface the hazard if that restore itself failed. The stream error is + // reported by the authoritative non-partial path in execute(); the rollback + // hazard is a different failure and nothing else in this path says so. + await this.cleanupFailedPartialStream(task) + } } } } diff --git a/src/core/tools/__tests__/readFileTool.spec.ts b/src/core/tools/__tests__/readFileTool.spec.ts index 52e04415ea..b97b17d063 100644 --- a/src/core/tools/__tests__/readFileTool.spec.ts +++ b/src/core/tools/__tests__/readFileTool.spec.ts @@ -14,13 +14,18 @@ import os from "os" import path from "path" +import type { Stats } from "fs" + +import type { LegacyReadFileParams } from "@roo-code/types" import type { ToolUse } from "../../../shared/tools" import type { Task, ToolExecutionContext } from "../../task/Task" import { isBinaryFile } from "isbinaryfile" +import { MAX_LINE_LENGTH } from "../../prompts/tools/native-tools/read_file" import { readFileTool } from "../ReadFileTool" +import { ObservationRegistry } from "../../task/observationRegistry" import { formatResponse } from "../../prompts/responses" import { validateImageForProcessing, processImageFile, isSupportedImageFormat } from "../helpers/imageHelpers" import { extractTextFromFile, getSupportedBinaryFormats } from "../../../integrations/misc/extract-text" @@ -135,13 +140,26 @@ interface MockTaskOptions { rooIgnoreAllowed?: boolean maxImageFileSize?: number maxTotalImageSize?: number + observationRegistry?: ObservationRegistry + aborted?: boolean } function createMockTask(options: MockTaskOptions = {}) { - const { supportsImages = false, rooIgnoreAllowed = true, maxImageFileSize = 5, maxTotalImageSize = 20 } = options + const { + supportsImages = false, + rooIgnoreAllowed = true, + maxImageFileSize = 5, + maxTotalImageSize = 20, + aborted = false, + } = options return { cwd: "/test/workspace", + // Mirror Task.abort: disposal and cancellation both set it before the loop resumes. + abort: aborted, + // Mirror Task: every task always owns an observation registry (A2, #1375). + // Tests asserting on observations pass their own instance via options. + observationRegistry: options.observationRegistry ?? new ObservationRegistry(), api: { getModel: vi.fn().mockReturnValue({ info: { supportsImages }, @@ -188,7 +206,18 @@ describe("ReadFileTool", () => { vi.clearAllMocks() // Default mock implementations - mockedFsStat.mockResolvedValue({ isDirectory: () => false } as any) + // The stat default carries BigIntStats fields (A2, epic #1375): reads now + // token-ize the pre/post stats, so the default must look like a real bigint stat. + // Tests overriding it do so per-call with mockResolvedValue(Once). + mockedFsStat.mockResolvedValue({ + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + // Cast: the mock only implements the members the tool and versionToken read. + } as unknown as Stats) mockedIsBinaryFile.mockResolvedValue(false) mockedFsReadFile.mockResolvedValue(Buffer.from("test content")) mockedReadWithSlice.mockReturnValue({ @@ -975,7 +1004,7 @@ describe("ReadFileTool", () => { mockTask.ask.mockResolvedValue({ response: "yesButtonClicked", text: undefined, images: undefined }) // fs.readFile with "utf8" encoding returns a string, not a Buffer - mockedFsReadFile.mockResolvedValue("line1\nline2\nline3\nline4\nline5" as any) + mockedFsReadFile.mockResolvedValue(Buffer.from("line1\nline2\nline3\nline4\nline5")) await readFileTool.execute( { files: [{ path: "test.ts", lineRanges: [{ start: 2, end: 4 }] }] } as any, @@ -1347,6 +1376,64 @@ describe("ReadFileTool", () => { expect(callbacks.pushToolResult).toHaveBeenCalledWith(expect.stringContaining("To read more")) }) + it("should show a clipping notice in indentation mode separately from the omission notice", async () => { + const mockTask = createMockTask() + const callbacks = createMockCallbacks() + + mockedFsReadFile.mockResolvedValue(Buffer.from("content")) + mockedReadWithIndentation.mockReturnValue({ + content: "1 | block", + returnedLines: 10, + totalLines: 100, + wasTruncated: false, + hasClippedLines: true, + includedRanges: [[1, 10]], + }) + + await readFileTool.execute( + { + path: "test.ts", + mode: "indentation", + indentation: { anchor_line: 1 }, + }, + mockTask as unknown as Task, + callbacks, + ) + + const pushed = callbacks.pushToolResult.mock.calls[0][0] as string + expect(pushed).toContain("clipped in this view") + expect(pushed).not.toContain("File content truncated") + }) + + it("should report clipping alongside truncation in indentation mode", async () => { + const mockTask = createMockTask() + const callbacks = createMockCallbacks() + + mockedFsReadFile.mockResolvedValue(Buffer.from("content")) + mockedReadWithIndentation.mockReturnValue({ + content: "1 | block", + returnedLines: 50, + totalLines: 200, + wasTruncated: true, + hasClippedLines: true, + includedRanges: [[1, 50]], + }) + + await readFileTool.execute( + { + path: "test.ts", + mode: "indentation", + indentation: { anchor_line: 1 }, + }, + mockTask as unknown as Task, + callbacks, + ) + + const pushed = callbacks.pushToolResult.mock.calls[0][0] as string + expect(pushed).toContain("File content truncated") + expect(pushed).toContain("clipped in this view") + }) + it("should include range information in indentation mode when not truncated", async () => { const mockTask = createMockTask() const callbacks = createMockCallbacks() @@ -1688,5 +1775,1050 @@ describe("ReadFileTool", () => { expect(mockTask.didToolFailInCurrentTurn).toBe(true) }) + + describe("observation registry", () => { + // Indices of fs.stat calls against a path ending in fileName, filtered by + // whether the call passed { bigint: true }. Counting matching calls is + // the load-bearing form here: toHaveBeenCalledWith asserts membership, + // which the directory-check stat alone satisfies, and it cannot tell a + // skipped stat from one that ran. + const usesBigintOptions = (options: unknown): boolean => + typeof options === "object" && options !== null && (options as { bigint?: unknown }).bigint === true + const statCallsMatching = (fileName: string, bigint: boolean): number[] => + mockedFsStat.mock.calls + .map((_, index) => index) + .filter((index) => { + const [statPath, options] = mockedFsStat.mock.calls[index] + return String(statPath).endsWith(fileName) && usesBigintOptions(options) === bigint + }) + // Vitest records invocationCallOrder parallel to mock.calls; comparing it + // against the readFile call tells the pre-read observation stat from the + // post-read one instead of trusting positional order by eye. + const statOrderBeforeRead = (statIndex: number): boolean => + mockedFsStat.mock.invocationCallOrder[statIndex] < mockedFsReadFile.mock.invocationCallOrder[0] + it("records an observation on successful read of an existing file", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + // Override the beforeEach default stat mock with proper BigIntStats. + mockedFsStat.mockResolvedValue({ + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + // Cast: the mock only implements the members the tool and versionToken read. + } as unknown as Stats) + mockedIsBinaryFile.mockResolvedValue(false) + + // Spy on observe to capture the exact key used (Windows path.resolve may use backslashes). + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute({ path: "existing.ts" }, mockTask as unknown as Task, callbacks) + + // Verify the tool called observe exactly once with a valid token. + expect(observeSpy).toHaveBeenCalledTimes(1) + const [calledPath, calledVersion] = observeSpy.mock.calls[0] + expect(calledPath).toContain("existing.ts") + expect(calledVersion).toMatch(/^\d+:\d+:\d+:\d+:\d+$/) + + // Verify get() returns the same data using the spy-captured key. + const obs = reg.get(calledPath) + expect(obs).toBeDefined() + expect(obs!.version).toBe(calledVersion) + // Regression evidence: both observation stats must be bigint stats. + // Count the calls that match - correct path AND { bigint: true } - + // because a membership assertion passes on its own: the read path + // also stats the same path without options for the directory check. + const bigintStatIndexes = statCallsMatching("existing.ts", true) + expect(bigintStatIndexes).toHaveLength(2) + // Neither observation stat is a plain stat: the directory check stays + // the only stat without options... + expect(statCallsMatching("existing.ts", false)).toHaveLength(1) + // ...and the two bigint stats bracket the read: exactly one before it + // (pre-read observation) and exactly one after (post-read observation). + expect(bigintStatIndexes.filter((index) => statOrderBeforeRead(index))).toHaveLength(1) + expect(bigintStatIndexes.filter((index) => !statOrderBeforeRead(index))).toHaveLength(1) + }) + + it("a failed read (absent path) leaves the registry size 0 and does not throw", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsReadFile.mockRejectedValue(new Error("ENOENT")) + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute({ path: "missing.ts" }, mockTask as unknown as Task, callbacks) + + // observationRegistry is guaranteed present because we passed it in createMockTask. + const reg = mockTask.observationRegistry + expect(reg).toBeDefined() + expect(reg!.size).toBe(0) + }) + + it("records an observation for legacy-format reads of existing files", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue({ + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + // Cast: the mock only implements the members the tool and versionToken read. + } as unknown as Stats) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + // Typed legacy (pre-refactor) params: the multi-file format with the + // _legacyFormat discriminant (see LegacyReadFileParams). + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy.ts" }], + _legacyFormat: true, + } + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [calledPath, calledVersion] = observeSpy.mock.calls[0] + expect(calledPath).toContain("legacy.ts") + expect(calledVersion).toMatch(/^\d+:\d+:\d+:\d+:\d+$/) + // Regression evidence, same contract on the legacy path: count the + // matching calls (correct path AND { bigint: true }) instead of + // asserting membership, which the directory-check stat alone satisfies. + const bigintStatIndexes = statCallsMatching("legacy.ts", true) + expect(bigintStatIndexes).toHaveLength(2) + expect(statCallsMatching("legacy.ts", false)).toHaveLength(1) + // The two bigint stats bracket the read: pre-read before it, post-read after. + expect(bigintStatIndexes.filter((index) => statOrderBeforeRead(index))).toHaveLength(1) + expect(bigintStatIndexes.filter((index) => !statOrderBeforeRead(index))).toHaveLength(1) + }) + + it("does not observe when the file mutates between the pre-read and post-read stats", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + const preStats = { + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + } + // A mutation lands mid-read: the post-read stat differs. + const postStats = { ...preStats, size: BigInt(301) } + + // Call order: directory check, pre-read stat, post-read stat. + mockedFsStat + .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) + .mockResolvedValueOnce(preStats as unknown as Stats) + .mockResolvedValueOnce(postStats as unknown as Stats) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute({ path: "mutated.ts" }, mockTask as unknown as Task, callbacks) + + // The read itself succeeded, but the target stays unobserved: the content the + // model received is not the on-disk state, so observing it would let a later + // write match a token the model never saw. + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + expect(mockTask.didToolFailInCurrentTurn).toBe(false) + }) + + it("records nothing when the task is aborted before the post-read stat (native path)", async () => { + // Task.disposeOnce() sets abort before an awaited read resumes, and abortTask() + // sets it on cancellation. The read still answers the model, but the observation - + // and the post-read stat work behind it - must not repopulate a retired registry. + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + aborted: true, + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue({ + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + // Cast: the mock only implements the members the tool and versionToken read. + } as unknown as Stats) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute({ path: "existing.ts" }, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + expect(mockTask.didToolFailInCurrentTurn).toBe(false) + // The abort must skip only the post-read observation: the pre-read + // observation stat is still issued, and no bigint stat follows the + // read. Counted by matching calls (correct path AND { bigint: true }): + // a membership assertion cannot tell "post-stat skipped" from + // "post-stat ran". + const bigintStatIndexes = statCallsMatching("existing.ts", true) + expect(bigintStatIndexes).toHaveLength(1) + // The single bigint stat ran before the read: it is the pre-read one. + expect(statOrderBeforeRead(bigintStatIndexes[0])).toBe(true) + // The directory-check stat is untouched: still exactly one plain stat. + expect(statCallsMatching("existing.ts", false)).toHaveLength(1) + }) + + it("records nothing when the task is aborted before the post-read stat (legacy path)", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + aborted: true, + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue({ + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + // Cast: the mock only implements the members the tool and versionToken read. + } as unknown as Stats) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy.ts" }], + _legacyFormat: true, + } + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + // Same contract on the legacy path: the pre-read observation stat is + // still issued and the post-read one is skipped - counted by matching + // calls, not by membership. + const bigintStatIndexes = statCallsMatching("legacy.ts", true) + expect(bigintStatIndexes).toHaveLength(1) + expect(statOrderBeforeRead(bigintStatIndexes[0])).toBe(true) + expect(statCallsMatching("legacy.ts", false)).toHaveLength(1) + }) + + it("records nothing when the task is cancelled while the post-read stat is in flight (native path)", async () => { + // The guard before the stat cannot see a cancellation that lands DURING the + // stat. The re-check before observe() is what keeps a read that belongs to a + // cancelled run out of the registry - and out of a registry that disposal has + // already retired. + const mockTask = createMockTask({ observationRegistry: new ObservationRegistry() }) + const callbacks = createMockCallbacks() + + const stats = { + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + // Cast: the mock only implements the members the tool and versionToken read. + } as unknown as Stats + mockedFsStat + .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) // directory check + .mockResolvedValueOnce(stats) // pre-read + .mockImplementationOnce(async () => { + // The cancel lands while this await is pending. + mockTask.abort = true + return stats + }) // post-read + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute({ path: "existing.ts" }, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + // The read itself still answered the model; only the observation is withheld. + expect(mockTask.didToolFailInCurrentTurn).toBe(false) + }) + + it("records nothing when the task is cancelled while the post-read stat is in flight (legacy path)", async () => { + const mockTask = createMockTask({ observationRegistry: new ObservationRegistry() }) + const callbacks = createMockCallbacks() + + const stats = { + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + // Cast: the mock only implements the members the tool and versionToken read. + } as unknown as Stats + mockedFsStat + .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) // directory check + .mockResolvedValueOnce(stats) // pre-read + .mockImplementationOnce(async () => { + // The cancel lands while this await is pending. + mockTask.abort = true + return stats + }) // post-read + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy.ts" }], + _legacyFormat: true, + } + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + }) + + it("leaves the target unobserved without failing the read when the pre-read stat fails", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + // Directory check OK; the pre-read stat fails (caught, target unobserved). + mockedFsStat + .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) + .mockRejectedValueOnce(new Error("EACCES")) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute({ path: "stat-fail.ts" }, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + // The read still succeeds — a stat failure never fails the read. + expect(mockTask.didToolFailInCurrentTurn).toBe(false) + // Assert the pushed payload, not just that something was pushed. + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("File: stat-fail.ts") + expect(pushed).toContain("test content") + expect(pushed).not.toContain("Error:") + }) + + it("leaves the target unobserved without failing the read when the post-read stat fails", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + const okStats = { + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + } + // Directory check and pre-read stat OK; the post-read stat fails. + mockedFsStat + .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) + .mockResolvedValueOnce(okStats as unknown as Stats) + .mockRejectedValueOnce(new Error("EACCES")) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute({ path: "post-stat-fail.ts" }, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + expect(mockTask.didToolFailInCurrentTurn).toBe(false) + // Assert the pushed payload, not just that something was pushed. + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("File: post-stat-fail.ts") + expect(pushed).toContain("test content") + expect(pushed).not.toContain("Error:") + }) + + it("legacy format: does not observe when the file mutates between the pre-read and post-read stats", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + const preStats = { + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + } + // Call order: directory check, pre-read stat, post-read stat (mutated). + mockedFsStat + .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) + .mockResolvedValueOnce(preStats as unknown as Stats) + .mockResolvedValueOnce({ ...preStats, size: BigInt(301) } as unknown as Stats) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy-mutated.ts" }], + _legacyFormat: true, + } + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + expect(mockTask.didToolFailInCurrentTurn).toBe(false) + }) + + it("legacy format: leaves the target unobserved when a stat fails without failing the read", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + // Directory check OK; the pre-read stat fails (caught, target unobserved). + mockedFsStat + .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) + .mockRejectedValueOnce(new Error("EACCES")) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy-stat-fail.ts" }], + _legacyFormat: true, + } + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + expect(mockTask.didToolFailInCurrentTurn).toBe(false) + // Assert the pushed payload, not just that something was pushed. + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("File: legacy-stat-fail.ts") + expect(pushed).toContain("test content") + expect(pushed).not.toContain("Error:") + }) + it("legacy format: leaves the target unobserved when the post-read stat fails", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + const okStats = { + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + } + // Directory check and pre-read stat OK; the post-read stat fails. + mockedFsStat + .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) + .mockResolvedValueOnce(okStats as unknown as Stats) + .mockRejectedValueOnce(new Error("EACCES")) + mockedIsBinaryFile.mockResolvedValue(false) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy-post-stat-fail.ts" }], + _legacyFormat: true, + } + + // Cast: the mock task only implements the members ReadFileTool.execute touches. + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).not.toHaveBeenCalled() + expect(reg.size).toBe(0) + expect(mockTask.didToolFailInCurrentTurn).toBe(false) + // Assert the pushed payload, not just that something was pushed. + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("File: legacy-post-stat-fail.ts") + expect(pushed).toContain("test content") + expect(pushed).not.toContain("Error:") + }) + it("two separate Task-owned registries are independent", async () => { + const regA = new ObservationRegistry() + const regB = new ObservationRegistry() + regA.observe("/shared.ts", "v1") + expect(regA.get("/shared.ts")!.version).toBe("v1") + expect(regB.get("/shared.ts")).toBeUndefined() + regB.observe("/shared.ts", "v2") + expect(regA.get("/shared.ts")!.version).toBe("v1") + expect(regB.get("/shared.ts")!.version).toBe("v2") + }) + }) + + describe("read completeness scope (S4b follow-up #46)", () => { + // The stat mock only implements the members the tool and versionToken read. + const bigintStats = (): Stats => + ({ + isDirectory: () => false, + dev: BigInt(1), + ino: BigInt(2), + size: BigInt(300), + mtimeNs: BigInt(4_000_000_000n), + ctimeNs: BigInt(5_000_000_000n), + }) as unknown as Stats + + it("native: a full, untruncated slice read from line 1 records a complete observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\n")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\n2 | b", + returnedLines: 2, + totalLines: 2, + wasTruncated: false, + includedRanges: [[1, 2]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + await readFileTool.execute({ path: "full.ts" }, mockTask as unknown as Task, callbacks) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [calledPath, calledVersion, calledComplete] = observeSpy.mock.calls[0] + expect(calledPath).toContain("full.ts") + expect(calledVersion).toMatch(/^\d+:\d+:\d+:\d+:\d+$/) + expect(calledComplete).toBe(true) + expect(reg.get(calledPath)!.complete).toBe(true) + }) + + it("native: a truncated slice read records a partial observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc\nd\ne")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a", + returnedLines: 1, + totalLines: 5, + wasTruncated: true, + includedRanges: [[1, 1]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + await readFileTool.execute( + { path: "trunc.ts", offset: 1, limit: 1 }, + mockTask as unknown as Task, + callbacks, + ) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [calledPath, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + expect(reg.get(calledPath)!.complete).toBe(false) + }) + + it("native: a full read whose line content was clipped records a partial observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\n")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\n2 | b", + returnedLines: 2, + totalLines: 2, + wasTruncated: false, + hasClippedLines: true, + includedRanges: [[1, 2]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + await readFileTool.execute({ path: "clipped.ts" }, mockTask as unknown as Task, callbacks) + + const [, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + // Every line was returned, so the notice must not point at a next + // offset that is beyond the file. + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("clipped in this view") + expect(pushed).not.toContain("To read more") + // The notice is added on top of the read, it does not replace it. + expect(pushed).toContain("1 | a") + }) + + it("native: a clipped full read joins the notice and the read with the exact separator", async () => { + // Review row 4202836427: in the clipped-but-not-truncated branch the two + // sentences and the read are joined by a specific separator, and that join is + // what tells the model every line was returned but some were cut. Assert the + // separator and both ends of the response rather than a loose substring. + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\n")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\n2 | b", + returnedLines: 2, + totalLines: 2, + wasTruncated: false, + hasClippedLines: true, + includedRanges: [[1, 2]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + await readFileTool.execute( + { path: "clipped-full.ts", offset: 1 }, + mockTask as unknown as Task, + callbacks, + ) + + const pushed = callbacks.pushToolResult.mock.calls[0][0] + // The header line and the notice are adjacent: the notice is the first thing + // after the file identity, and the character cap it names is the one the tool + // actually applied. + expect( + pushed.startsWith( + `File: clipped-full.ts\nIMPORTANT: Some lines exceed ${MAX_LINE_LENGTH} characters and were clipped in this view.`, + ), + ).toBe(true) + expect(pushed).toContain( + "were clipped in this view. The file was read in full, but the clipped lines were not shown in full.", + ) + expect(pushed.endsWith("were not shown in full.\n1 | a\n2 | b")).toBe(true) + expect(pushed).toContain("The file was read in full") + // Every line was returned, so the notice must not advertise a next offset. + expect(pushed).not.toContain("To read more") + // The read stays incomplete: the clipped tails were never shown, so a + // full-file replacement must not be built from this view. + const [, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + }) + it("native: a clipped slice that starts after line 1 names the slice instead of claiming a full read", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc\nd\ne\n")) + mockedReadWithSlice.mockReturnValue({ + content: "3 | c\n4 | d", + returnedLines: 2, + totalLines: 5, + wasTruncated: false, + hasClippedLines: true, + includedRanges: [[3, 4]], + }) + + await readFileTool.execute( + { path: "clipped-slice.ts", offset: 3 }, + mockTask as unknown as Task, + callbacks, + ) + + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("clipped in this view") + // Lines 1-2 were omitted, so the notice must describe the slice that was + // returned rather than claim the whole file was read. + expect(pushed).toContain("starts at line 3") + expect(pushed).not.toContain("The file was read in full") + expect(pushed).toContain("3 | c") + }) + + it("native: a truncated slice that also clipped a line reports both notices", async () => { + // A long line inside a slice that also cut lines off is a plausible case, + // and the response has to say both things. + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\n2 | b", + returnedLines: 2, + totalLines: 3, + wasTruncated: true, + hasClippedLines: true, + includedRanges: [[1, 2]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + await readFileTool.execute({ path: "both.ts" }, mockTask as unknown as Task, callbacks) + + const [, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("Showing lines 1-2 of 3 total lines") + expect(pushed).toContain("clipped in this view") + }) + + it("native: an offset read that is not truncated still records a partial observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc\nd\ne")) + mockedReadWithSlice.mockReturnValue({ + content: "4 | d\n5 | e", + returnedLines: 2, + totalLines: 5, + wasTruncated: false, + includedRanges: [[4, 5]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + await readFileTool.execute( + { path: "offset.ts", offset: 4, limit: 2 }, + mockTask as unknown as Task, + callbacks, + ) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [_calledPath, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + }) + + it("native: an indentation-mode block read records a partial observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("function f() { return 1 }")) + mockedReadWithIndentation.mockReturnValue({ + content: "10 | function f() {", + wasTruncated: false, + includedRanges: [[10, 20]], + totalLines: 100, + returnedLines: 11, + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + await readFileTool.execute( + { path: "indent.ts", mode: "indentation" }, + mockTask as unknown as Task, + callbacks, + ) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [_calledPath, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + }) + + it("legacy: a line-range read records a partial observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc\nd\ne")) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "ranges.ts", lineRanges: [{ start: 2, end: 4 }] }], + _legacyFormat: true, + } + + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [calledPath, , calledComplete] = observeSpy.mock.calls[0] + expect(calledPath).toContain("ranges.ts") + expect(calledComplete).toBe(false) + }) + + it("legacy: a full, untruncated slice read records a complete observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\n2 | b", + returnedLines: 2, + totalLines: 2, + wasTruncated: false, + includedRanges: [[1, 2]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy-full.ts" }], + _legacyFormat: true, + } + + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [_calledPath, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(true) + + // Nothing was omitted and nothing was clipped, so no note is added. + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).not.toContain("clipped in this view") + expect(pushed).not.toContain("total lines") + }) + + it("legacy: a full read with a clipped line records a partial observation and reports the clipping", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\n2 | b", + returnedLines: 2, + totalLines: 2, + wasTruncated: false, + hasClippedLines: true, + includedRanges: [[1, 2]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy-clipped.ts" }], + _legacyFormat: true, + } + + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + const [, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + + // Every line was returned, so the note reports the clipping instead of + // a showing-N-of-N count that would point past the file. + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("clipped in this view") + expect(pushed).not.toContain("showing 2 of 2 total lines") + }) + + it("legacy: a truncated slice that also clipped a line reports both notices", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\n2 | b", + returnedLines: 2, + totalLines: 3, + wasTruncated: true, + hasClippedLines: true, + includedRanges: [[1, 2]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy-both.ts" }], + _legacyFormat: true, + } + + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + const [, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("showing 2 of 3 total lines") + expect(pushed).toContain("clipped in this view") + }) + + it("legacy: a slice truncated to the default limit records a partial observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc")) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a", + returnedLines: 1, + totalLines: 5000, + wasTruncated: true, + includedRanges: [[1, 1]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy-trunc.ts" }], + _legacyFormat: true, + } + + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [_calledPath, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + + // Lines were omitted here, so the note reports the omitted range rather + // than clipping. + const pushed = callbacks.pushToolResult.mock.calls[0][0] + expect(pushed).toContain("showing 1 of 5000 total lines") + }) + + it("native: a read whose bytes did not survive the UTF-8 decode records a partial observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + // 0xFF is not valid UTF-8, so the model receives U+FFFD instead of the byte. + const raw = Buffer.from([0x61, 0xff]) + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(raw) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\uFFFD", + returnedLines: 1, + totalLines: 1, + wasTruncated: false, + includedRanges: [[1, 1]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + await readFileTool.execute({ path: "lossy.ts" }, mockTask as unknown as Task, callbacks) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [calledPath, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + expect(reg.get(calledPath)!.complete).toBe(false) + }) + + it("legacy: a read whose bytes did not survive the UTF-8 decode records a partial observation", async () => { + const mockTask = createMockTask({ + observationRegistry: new ObservationRegistry(), + }) + const callbacks = createMockCallbacks() + + const raw = Buffer.from([0x61, 0xff]) + mockedFsStat.mockResolvedValue(bigintStats()) + mockedIsBinaryFile.mockResolvedValue(false) + mockedFsReadFile.mockResolvedValue(raw) + mockedReadWithSlice.mockReturnValue({ + content: "1 | a\uFFFD", + returnedLines: 1, + totalLines: 1, + wasTruncated: false, + includedRanges: [[1, 1]], + }) + + const reg = mockTask.observationRegistry! + const observeSpy = vi.spyOn(reg, "observe") + + const legacyParams: LegacyReadFileParams = { + files: [{ path: "legacy-lossy.ts" }], + _legacyFormat: true, + } + + await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks) + + expect(observeSpy).toHaveBeenCalledTimes(1) + const [calledPath, , calledComplete] = observeSpy.mock.calls[0] + expect(calledComplete).toBe(false) + expect(reg.get(calledPath)!.complete).toBe(false) + }) + }) }) }) diff --git a/src/core/tools/__tests__/writeToFileTool-partial-state-cleanup.spec.ts b/src/core/tools/__tests__/writeToFileTool-partial-state-cleanup.spec.ts new file mode 100644 index 0000000000..8964a66e82 --- /dev/null +++ b/src/core/tools/__tests__/writeToFileTool-partial-state-cleanup.spec.ts @@ -0,0 +1,338 @@ +// npx vitest run core/tools/__tests__/writeToFileTool-partial-state-cleanup.spec.ts + +import { RooCodeEventName } from "@roo-code/types" +import { vi, type MockedFunction } from "vitest" + +import { type Task } from "../../task/Task" +import { writeToFileTool } from "../WriteToFileTool" + +// The cleanup primitives only read these members, so a structural double is enough; +// the double assertion is the repo's existing pattern for private-method tests +// (see src/__tests__/removeClineFromStack-delegation.spec.ts). +interface CleanupTask { + taskId: string + instanceId: string + once: MockedFunction<(...args: unknown[]) => unknown> + off: MockedFunction<(...args: unknown[]) => unknown> + diffViewProvider: { + reset: MockedFunction<() => Promise> + discardUnapprovedStream: MockedFunction<() => Promise> + revertChanges: MockedFunction<() => Promise> + /** Whether this edit still owns the empty placeholder open() created for a new file. */ + ownsPlaceholder: boolean + } + finalizePartialToolAsk: MockedFunction<() => Promise> + say: MockedFunction<(...args: unknown[]) => Promise> +} + +function buildTask(taskId: string, instanceId: string): Task { + const task: CleanupTask = { + taskId, + instanceId, + once: vi.fn(), + off: vi.fn(), + diffViewProvider: { + reset: vi.fn().mockResolvedValue(undefined), + revertChanges: vi.fn().mockResolvedValue(undefined), + discardUnapprovedStream: vi.fn().mockResolvedValue(undefined), + // The default scenario is a delta over an EXISTING file: no placeholder ownership is + // at stake, so the only reason a failed restore has to keep a session is the + // unapproved content still sitting in the buffer. + ownsPlaceholder: false, + }, + finalizePartialToolAsk: vi.fn().mockResolvedValue(undefined), + say: vi.fn().mockResolvedValue(undefined), + } + return task as unknown as Task +} + +describe("WriteToFileTool per-task partial-state cleanup", () => { + afterEach(() => { + writeToFileTool["taskPartialStreamState"].clear() + vi.restoreAllMocks() + }) + + it("releases the task state and deregisters the abort listener", async () => { + const task = buildTask("cleanup-task", "inst-1") + const state = writeToFileTool["getTaskPartialStreamState"](task) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + + writeToFileTool.clearTaskState(task) + + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect((task as unknown as CleanupTask).off).toHaveBeenCalledWith( + RooCodeEventName.TaskAborted, + state.abortCleanup, + ) + }) + + it("is a no-op for a task that never streamed", async () => { + const task = buildTask("never-streamed", "inst-2") + + writeToFileTool.clearTaskState(task) + + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect((task as unknown as CleanupTask).off).not.toHaveBeenCalled() + }) + + it("logs and continues when resetting the diff view fails", async () => { + const task = buildTask("reset-fails", "inst-3") + const t = task as unknown as CleanupTask + t.diffViewProvider.reset = vi.fn().mockRejectedValue(new Error("reset failed")) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await writeToFileTool["resetDiffViewAfterWrite"](task) + + expect(errorSpy).toHaveBeenCalledWith("Error resetting write_to_file diff view:", expect.any(Error)) + }) + + it("logs and continues when discarding the unapproved diff view fails", async () => { + const task = buildTask("revert-fails", "inst-4") + const t = task as unknown as CleanupTask + t.diffViewProvider.discardUnapprovedStream = vi.fn().mockRejectedValue(new Error("revert failed")) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await writeToFileTool["discardUnapprovedStreamBeforeReset"](task) + + expect(errorSpy).toHaveBeenCalledWith( + "Error discarding the unapproved write_to_file diff view:", + expect.any(Error), + ) + }) + + it("discards while the recovery state exists and reports the hazard when the discard fails", async () => { + const task = buildTask("revert-fails-teardown", "inst-6") + const t = task as unknown as CleanupTask + let stateSizeDuringRevert = -1 + t.diffViewProvider.discardUnapprovedStream = vi.fn(async () => { + // The recovery state must still be present while the rollback runs. + stateSizeDuringRevert = writeToFileTool["taskPartialStreamState"].size + throw new Error("revert failed") + }) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + // Seed the per-task stream state so this teardown boundary is taken at all, and mark it as a + // stream that reached the diff view: that is the preview the hook below owes a rollback, and + // ownsPreview is the flag it checks before touching the view. + const seededState = writeToFileTool["getTaskPartialStreamState"](task) + seededState.ownsPreview = true + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + + const handled = await writeToFileTool["onParameterParseFailure"]( + task, + // Only handleError is reached when no streaming error was recorded; the + // structural double is the existing pattern in this file. + { handleError: vi.fn().mockResolvedValue(undefined) } as unknown as Parameters< + (typeof writeToFileTool)["onParameterParseFailure"] + >[1], + new Error("parameter parse failed"), + ) + + // A failed rollback is not a completed teardown: the user is told the editor may + // still hold content the task never approved. + expect(t.say).toHaveBeenCalledWith("error", expect.stringContaining("unapproved")) + expect(stateSizeDuringRevert).toBe(1) + // The restore failed over an existing file, so the buffer can still hold that + // unapproved content: the recovery state AND the diff session have to survive, or + // nothing is left that knows this path still owes a rollback. + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + expect(t.diffViewProvider.reset).not.toHaveBeenCalled() + expect(t.off).not.toHaveBeenCalled() + expect(handled).toBe(false) + // The retained entry is still tearable: clearing the task state releases the + // bookkeeping and deregisters the abort listener it registered. + writeToFileTool.clearTaskState(task) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect(t.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, seededState.abortCleanup) + errorSpy.mockRestore() + }) + + it("reports the rollback hazard AND the retained streaming error, and returns true", async () => { + const task = buildTask("revert-fails-with-stream-error", "inst-7") + const t = task as unknown as CleanupTask + t.diffViewProvider.discardUnapprovedStream = vi.fn().mockRejectedValue(new Error("revert failed")) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + const state = writeToFileTool["getTaskPartialStreamState"](task) + // The scenario stands for a delta that had already streamed into the diff view - that is + // the preview this teardown is on the hook to roll back - and ownsPreview is the flag the + // parse-failure hook checks before it touches the view. + state.ownsPreview = true + const streamError = new Error("filesystem failure while streaming") + state.streamFailed = true + state.streamError = streamError + const handleError = vi.fn().mockResolvedValue(undefined) + + const handled = await writeToFileTool["onParameterParseFailure"]( + task, + { handleError } as unknown as Parameters<(typeof writeToFileTool)["onParameterParseFailure"]>[1], + new Error("parameter parse failed"), + ) + + // Both reports happen: the rollback hazard and the error the user can act on. + expect(t.say).toHaveBeenCalledWith("error", expect.stringContaining("unapproved")) + expect(handleError).toHaveBeenCalledWith("writing file", streamError) + expect(handled).toBe(true) + errorSpy.mockRestore() + }) + + it("still reports the streaming error when the rollback warning itself fails", async () => { + const task = buildTask("rollback-warning-fails", "inst-8") + const t = task as unknown as CleanupTask + t.diffViewProvider.discardUnapprovedStream = vi.fn().mockRejectedValue(new Error("revert failed")) + t.say = vi.fn().mockRejectedValue(new Error("say failed")) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + const state = writeToFileTool["getTaskPartialStreamState"](task) + // The scenario stands for a delta that had already streamed into the diff view - that is + // the preview this teardown is on the hook to roll back - and ownsPreview is the flag the + // parse-failure hook checks before it touches the view. + state.ownsPreview = true + const streamError = new Error("filesystem failure while streaming") + state.streamFailed = true + state.streamError = streamError + const handleError = vi.fn().mockResolvedValue(undefined) + + const handled = await writeToFileTool["onParameterParseFailure"]( + task, + { handleError } as unknown as Parameters<(typeof writeToFileTool)["onParameterParseFailure"]>[1], + new Error("parameter parse failed"), + ) + + // A failing report must not abort the teardown: the streaming error still lands. + expect(errorSpy).toHaveBeenCalledWith("Error reporting write_to_file rollback failure:", expect.any(Error)) + expect(handleError).toHaveBeenCalledWith("writing file", streamError) + expect(handled).toBe(true) + errorSpy.mockRestore() + }) + + it("surfaces the rollback hazard from the failed-stream cleanup as well", async () => { + const task = buildTask("failed-stream-cleanup", "inst-9") + const t = task as unknown as CleanupTask + t.diffViewProvider.discardUnapprovedStream = vi.fn().mockRejectedValue(new Error("revert failed")) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await writeToFileTool["cleanupFailedPartialStream"](task) + + // Same contract as the parse-failure teardown: a failed restore is reported. + expect(t.say).toHaveBeenCalledWith("error", expect.stringContaining("unapproved")) + // The restore failed over an existing file, so the diff session survives with it: + // resetting here would forget that this path still owes a rollback. + expect(t.diffViewProvider.reset).not.toHaveBeenCalled() + errorSpy.mockRestore() + }) + + it("stays silent when the failed-stream cleanup restored the editor", async () => { + // Every other case here makes the discard reject, so a cleanup that warned after EVERY + // restore still passed. "The editor may hold content you never approved" is only true when + // the restore failed; saying it regardless trains the user to ignore the warning. + const task = buildTask("failed-stream-clean", "inst-10") + const t = task as unknown as CleanupTask + + await writeToFileTool["cleanupFailedPartialStream"](task) + + expect(t.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + expect(t.diffViewProvider.reset).toHaveBeenCalledTimes(1) + expect(t.say).not.toHaveBeenCalled() + }) + + it("stays silent when the parse-failure teardown restored the editor", async () => { + // The same contract on the other teardown boundary: a completed restore is not a hazard, + // so nothing is reported and the incidental parse error is left to the caller. + const task = buildTask("parse-failure-clean", "inst-11") + const t = task as unknown as CleanupTask + // The scenario owns the preview the teardown below is responsible for, and ownsPreview is + // the flag the hook checks before it touches the view. + writeToFileTool["getTaskPartialStreamState"](task).ownsPreview = true + const handleError = vi.fn().mockResolvedValue(undefined) + + const handled = await writeToFileTool["onParameterParseFailure"]( + task, + { handleError } as unknown as Parameters<(typeof writeToFileTool)["onParameterParseFailure"]>[1], + new Error("parameter parse failed"), + ) + + expect(t.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + expect(t.say).not.toHaveBeenCalled() + expect(handleError).not.toHaveBeenCalled() + expect(handled).toBe(false) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + }) + + it("releases only its own bookkeeping when a parse failure follows a stream that never reached the view", async () => { + // The ownership case at this boundary: a stream whose path never stabilized still has + // state, and its final block can still fail to parse. The provider may be holding a + // session from an earlier call - together with the placeholder ownership that goes with + // it - and this stream never opened or updated that view, so the hook has to release the + // bookkeeping and leave the provider state alone: discarding or resetting here would throw + // away a session this stream does not own. + const task = buildTask("parse-failure-never-owned", "inst-12") + const t = task as unknown as CleanupTask + writeToFileTool["getTaskPartialStreamState"](task) + const handleError = vi.fn().mockResolvedValue(undefined) + + const handled = await writeToFileTool["onParameterParseFailure"]( + task, + { handleError } as unknown as Parameters<(typeof writeToFileTool)["onParameterParseFailure"]>[1], + new Error("parameter parse failed"), + ) + + expect(handled).toBe(false) + expect(t.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(t.diffViewProvider.reset).not.toHaveBeenCalled() + expect(t.say).not.toHaveBeenCalled() + expect(handleError).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + }) + + it("reports a retained streaming error without touching a view this stream never owned", async () => { + // Same ownership answer, with a filesystem failure on the books: the error is still + // the user's to act on, so it is reported with execute()'s "writing file" context - + // reporting it never required touching the other session's view. + const task = buildTask("never-owned-stream-error", "inst-13") + const t = task as unknown as CleanupTask + const state = writeToFileTool["getTaskPartialStreamState"](task) + const streamError = new Error("filesystem failure while streaming") + state.streamFailed = true + state.streamError = streamError + const handleError = vi.fn().mockResolvedValue(undefined) + + const handled = await writeToFileTool["onParameterParseFailure"]( + task, + { handleError } as unknown as Parameters<(typeof writeToFileTool)["onParameterParseFailure"]>[1], + new Error("parameter parse failed"), + ) + + expect(handled).toBe(true) + expect(handleError).toHaveBeenCalledWith("writing file", streamError) + expect(t.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(t.diffViewProvider.reset).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + }) + + it("logs and continues when finalizing the open partial ask fails", async () => { + const task = buildTask("finalize-fails", "inst-5") + const t = task as unknown as CleanupTask + t.finalizePartialToolAsk = vi.fn().mockRejectedValue(new Error("finalize failed")) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await writeToFileTool["finalizePartialToolAskAfterFailure"](task, "partial text") + + expect(errorSpy).toHaveBeenCalledWith("Error finalizing write_to_file partial tool ask:", expect.any(Error)) + }) + + it("keeps the diff session when the cleanup could not restore an existing file", async () => { + // The class the review named, pinned on its own: the restore refused, the file is an + // existing one, so ownsPlaceholder is false and the old code reset the view anyway. + // That reset cleared isEditing and relPath - the only thing telling a later call that + // this path still owes a rollback - while the buffer went on holding content the task + // never approved, one save away from landing on disk. + const task = buildTask("failed-stream-existing-file", "inst-14") + const t = task as unknown as CleanupTask + t.diffViewProvider.discardUnapprovedStream = vi.fn().mockRejectedValue(new Error("revert failed")) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await writeToFileTool["cleanupFailedPartialStream"](task) + + expect(t.diffViewProvider.reset).not.toHaveBeenCalled() + expect(t.say).toHaveBeenCalledWith("error", expect.stringContaining("unapproved")) + errorSpy.mockRestore() + }) +}) diff --git a/src/core/tools/__tests__/writeToFileTool.spec.ts b/src/core/tools/__tests__/writeToFileTool.spec.ts index 7cb9d01585..c67f0e84e1 100644 --- a/src/core/tools/__tests__/writeToFileTool.spec.ts +++ b/src/core/tools/__tests__/writeToFileTool.spec.ts @@ -1,11 +1,13 @@ import * as path from "path" +import { RooCodeEventName } from "@roo-code/types" import type { MockedFunction } from "vitest" import { fileExistsAtPath, createDirectoriesForFile } from "../../../utils/fs" import { isPathOutsideWorkspace } from "../../../utils/pathUtils" import { getReadablePath } from "../../../utils/path" import { unescapeHtmlEntities } from "../../../utils/text-normalization" +import { DiffViewProvider } from "../../../integrations/editor/DiffViewProvider" import { everyLineHasLineNumbers, stripLineNumbers } from "../../../integrations/misc/extract-text" import { ToolUse, ToolResponse, AskApproval, HandleError, PushToolResult } from "../../../shared/tools" import { writeToFileTool } from "../WriteToFileTool" @@ -69,6 +71,10 @@ vi.mock("../../../integrations/misc/extract-text", () => ({ vi.mock("vscode", () => ({ window: { showWarningMessage: vi.fn().mockResolvedValue(undefined), + // The retained-session predicate this spec now drives lives on the real + // DiffViewProvider, and loading that module runs DecorationController's + // module-init decoration. + createTextEditorDecorationType: vi.fn(() => ({ dispose: vi.fn() })), }, env: { openExternal: vi.fn(), @@ -96,6 +102,19 @@ describe("writeToFileTool", () => { const testContent = "Line 1\nLine 2\nLine 3" const testContentWithMarkdown = "```javascript\nLine 1\nLine 2\n```" + // The exact payload handlePartial() streams as the partial `tool` ask for the default + // test scenario (new file, readable path, in-workspace, not write-protected). + // finalizePartialToolAsk() no-ops on a text mismatch, so finalize assertions must + // match this exactly: a weaker matcher (e.g. expect.any(String), which a relPath also + // satisfies) would pass a mutant that passes the wrong text and leaves the spinner stuck. + const expectedPartialToolMessage = JSON.stringify({ + tool: "newFileCreated", + path: "test/path.txt", + content: testContent, + isOutsideWorkspace: false, + isProtected: false, + }) + // Mocked functions with correct types const mockedFileExistsAtPath = fileExistsAtPath as MockedFunction const mockedCreateDirectoriesForFile = createDirectoriesForFile as MockedFunction @@ -118,6 +137,9 @@ describe("writeToFileTool", () => { mockedPathResolve.mockReturnValue(absoluteFilePath) mockedFileExistsAtPath.mockResolvedValue(false) + // vi.clearAllMocks() keeps the last mock implementation; reset the factory default here + // so no test depends on declaration order or an earlier test's rejection. + mockedCreateDirectoriesForFile.mockResolvedValue([]) mockedIsPathOutsideWorkspace.mockReturnValue(false) mockedGetReadablePath.mockReturnValue("test/path.txt") mockedUnescapeHtmlEntities.mockImplementation((content) => { @@ -128,6 +150,8 @@ describe("writeToFileTool", () => { return content }) + mockCline.taskId = "task-1" + mockCline.instanceId = "instance-1" mockCline.cwd = "/" mockCline.consecutiveMistakeCount = 0 mockCline.didEditFile = false @@ -147,10 +171,18 @@ describe("writeToFileTool", () => { editType: undefined, isEditing: false, originalContent: "", + // A retained-session contract used by execute(): the double reports no + // retained session and mirrors the provider's path comparison. + isEditingDifferentPath: vi.fn((_relPath: string) => false), + editingRelPath: undefined as string | undefined, + ownsPlaceholder: false, open: vi.fn().mockResolvedValue(undefined), update: vi.fn().mockResolvedValue(undefined), reset: vi.fn().mockResolvedValue(undefined), revertChanges: vi.fn().mockResolvedValue(undefined), + discardUnapprovedStream: vi.fn().mockResolvedValue(undefined), + discardOwnedPlaceholder: vi.fn().mockResolvedValue(undefined), + saveDirectly: vi.fn().mockResolvedValue(undefined), saveChanges: vi.fn().mockResolvedValue({ newProblemsMessage: "", userEdits: null, @@ -186,8 +218,12 @@ describe("writeToFileTool", () => { } mockCline.say = vi.fn().mockResolvedValue(undefined) mockCline.ask = vi.fn().mockResolvedValue(undefined) + mockCline.once = vi.fn() + mockCline.off = vi.fn() + mockCline.finalizePartialToolAsk = vi.fn().mockResolvedValue(undefined) mockCline.recordToolError = vi.fn() mockCline.sayAndCreateMissingParamError = vi.fn().mockResolvedValue("Missing param error") + mockCline.processQueuedMessages = vi.fn() mockAskApproval = vi.fn().mockResolvedValue(true) mockHandleError = vi.fn().mockResolvedValue(undefined) @@ -223,10 +259,13 @@ describe("writeToFileTool", () => { content: testContent, ...params, }, + // The harness builds deliberately malformed payloads (a missing or + // undefined path/content), which the typed args cannot express. One assertion + // through unknown keeps that case testable without introducing `any`. nativeArgs: { - path: (params.path ?? testFilePath) as any, - content: (params.content ?? testContent) as any, - }, + path: params.path ?? testFilePath, + content: params.content ?? testContent, + } as unknown as ToolUse<"write_to_file">["nativeArgs"], partial: isPartial, } @@ -288,18 +327,70 @@ describe("writeToFileTool", () => { ) it.skipIf(process.platform === "win32")( - "creates parent directories when path has stabilized (partial)", + "does not create directories in handlePartial -- only execute() creates them", async () => { - // First call - path not yet stabilized + // First call - path not yet stabilized, early return await executeWriteFileTool({}, { fileExists: false, isPartial: true }) expect(mockedCreateDirectoriesForFile).not.toHaveBeenCalled() - // Second call with same path - path is now stabilized + // Second call with same path - path stabilized, handlePartial runs but + // must NOT call createDirectoriesForFile (directory creation belongs in execute) await executeWriteFileTool({}, { fileExists: false, isPartial: true }) - expect(mockedCreateDirectoriesForFile).toHaveBeenCalledWith(absoluteFilePath) + expect(mockedCreateDirectoriesForFile).not.toHaveBeenCalled() }, ) + it("does not stream a different path's delta into a retained session", async () => { + // The retained session keeps isEditing true, so a different path's delta would + // skip open() and write its partial content into the old document. The streaming + // guard must leave the preview untouched and let execute() report the rejection. + mockCline.diffViewProvider.isEditing = true + mockCline.diffViewProvider.isEditingDifferentPath = vi.fn(() => true) + + await executeWriteFileTool({ path: "other.txt" }, { fileExists: false, isPartial: true }) + await executeWriteFileTool({ path: "other.txt" }, { fileExists: false, isPartial: true }) + + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.update).not.toHaveBeenCalled() + // The partial ask is opened before the guard used to run; the different-path + // stream must not leave a spinner behind in the first place. + expect(mockCline.ask).not.toHaveBeenCalledWith("tool", expect.anything(), true) + }) + + it("preserves the retained session when a different path's stream fails to parse", async () => { + // The retained session belongs to another, approved edit: a parse failure on a + // different path's stream must not discard or reset it. + mockCline.diffViewProvider.isEditing = true + mockCline.diffViewProvider.isEditingDifferentPath = vi.fn(() => true) + mockCline.diffViewProvider.discardUnapprovedStream.mockClear() + mockCline.diffViewProvider.reset.mockClear() + + await executeWriteFileTool({ path: "other.txt" }, { fileExists: false, isPartial: true }) + await executeWriteFileTool({ path: "other.txt" }, { fileExists: false, isPartial: true }) + + // Final block arrives without native arguments, so execute() is skipped and the + // parse-failure teardown runs. + const toolUse: ToolUse = { + type: "tool_use", + name: "write_to_file", + params: { path: "other.txt", content: "streamed content" }, + partial: false, + } + await writeToFileTool.handle(mockCline, toolUse as ToolUse<"write_to_file">, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + toolCallId: "test-tool-call-id", + }) + + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.revertChanges).not.toHaveBeenCalled() + expect(mockHandleError).toHaveBeenCalledWith("parsing write_to_file args", expect.any(Error)) + // The retained session's own delta is untouched. + expect(mockCline.diffViewProvider.update).not.toHaveBeenCalled() + }) + it("does not create directories when file exists", async () => { await executeWriteFileTool({}, { fileExists: true }) @@ -393,6 +484,25 @@ describe("writeToFileTool", () => { // Should process normally without issues expect(mockCline.consecutiveMistakeCount).toBe(0) }) + + it("does not report a successful write as failed when final diff reset rejects", async () => { + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + mockCline.diffViewProvider.reset.mockRejectedValue(new Error("reset failed")) + + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).not.toHaveBeenCalled() + expect(mockPushToolResult).toHaveBeenCalledWith("Tool result message") + expect(mockCline.didEditFile).toBe(true) + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error resetting write_to_file diff view:", + expect.any(Error), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) }) describe("partial block handling", () => { @@ -420,6 +530,745 @@ describe("writeToFileTool", () => { expect(mockCline.diffViewProvider.open).toHaveBeenCalledWith(testFilePath) expect(mockCline.diffViewProvider.update).toHaveBeenCalledWith(testContent, false) }) + it("does not share path stabilization between tasks with the same path", async () => { + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).not.toHaveBeenCalled() + + mockCline.taskId = "task-2" + mockCline.instanceId = "instance-2" + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).not.toHaveBeenCalled() + + mockCline.taskId = "task-1" + mockCline.instanceId = "instance-1" + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(1) + + mockCline.taskId = "task-2" + mockCline.instanceId = "instance-2" + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(2) + }) + + it("cleans per-task partial state when the task aborts before execute finalization", async () => { + let abortCleanup: (() => void) | undefined + mockCline.once.mockImplementation((event: RooCodeEventName, listener: () => void) => { + if (event === RooCodeEventName.TaskAborted) { + abortCleanup = listener + } + return mockCline + }) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(1) + expect(mockCline.once).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, expect.any(Function)) + + abortCleanup?.() + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortCleanup) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(1) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(2) + }) + + it("stops before the filesystem probe when the state is released while provider state is in flight", async () => { + // handlePartial() awaits provider.getState() before any side effect. A cancellation + // during that await runs the TaskAborted teardown; the delta already in flight must + // stop there instead of probing, asking and opening a diff view for a dead task. + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + mockCline.diffViewProvider.open.mockClear() + // Clear the cached editType so the filesystem probe branch is the one that would run: + // the check after provider.getState() is the only thing that can keep it from running. + mockCline.diffViewProvider.editType = undefined + mockedFileExistsAtPath.mockClear() + mockCline.providerRef.deref.mockReturnValue({ + getState: vi.fn(async () => { + writeToFileTool.clearTaskState(mockCline) + return {} + }), + }) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + // The probe is the first side effect after getState(): the check above is what keeps it + // from running for a cancelled task. + expect(mockedFileExistsAtPath).not.toHaveBeenCalled() + expect(mockCline.ask).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + }) + + it("stops before the partial ask when the state is released during the filesystem probe", async () => { + // Same teardown, one await later. The first delta pins editType, so clear it to take + // the fileExistsAtPath branch again and abort inside it. + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + mockCline.diffViewProvider.open.mockClear() + mockCline.diffViewProvider.editType = undefined + // mockImplementationOnce: executeWriteFileTool re-arms the default resolved value on + // every call, so a plain mockImplementation would be overwritten. + mockedFileExistsAtPath.mockImplementationOnce(async () => { + writeToFileTool.clearTaskState(mockCline) + return false + }) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.ask).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + }) + + it("stops before touching the diff view when the stream state is released during an in-flight ask", async () => { + // A cancellation while task.ask() is in flight runs the TaskAborted teardown. The delta + // that was already in flight must not then re-open the diff view for a task the user + // cancelled - that resurrects the state the teardown just released. + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + mockCline.diffViewProvider.open.mockClear() + mockCline.diffViewProvider.update.mockClear() + mockCline.ask.mockImplementation(async () => { + writeToFileTool.clearTaskState(mockCline) + }) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.update).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + }) + + it("stops before updating the diff view when the task is cancelled while open() is in flight", async () => { + // open() is the first provider await after the partial ask. If TaskAborted lands while + // it is in flight, the teardown has already released this task's stream state (and may + // have reverted or closed this very view), so the delta that is already in flight must + // not stream partial content into a cancelled task's view. + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + expect(mockCline.diffViewProvider.open).toHaveBeenCalledTimes(1) + mockCline.diffViewProvider.open.mockClear() + mockCline.diffViewProvider.update.mockClear() + mockCline.diffViewProvider.open.mockImplementationOnce(async () => { + writeToFileTool.clearTaskState(mockCline) + }) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.diffViewProvider.open).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.update).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + }) + + it("releases what the late open() completed when the task aborts during it", async () => { + // The cancellation teardown runs while open() is still pending, so it can only release + // what existed at that instant. open() then finishes its side effects: it creates the + // directories and the empty placeholder and sets isEditing + relPath on the provider. + // This stream's entry is already gone by then, so nothing owns those artifacts any + // more - a later write to the same path would find a session this task never opened. + // The cleanup below is therefore the only one that can cover what open() completed. + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + mockCline.diffViewProvider.isEditing = false + mockCline.diffViewProvider.open.mockClear() + mockCline.diffViewProvider.update.mockClear() + mockCline.diffViewProvider.discardUnapprovedStream.mockReset().mockResolvedValue(undefined) + mockCline.diffViewProvider.reset.mockClear() + let releasesAtOpenReturn = -1 + let resetsAtOpenReturn = -1 + mockCline.diffViewProvider.open.mockImplementationOnce(async () => { + // The cancellation lands mid-open, so the teardown releases this entry and rolls + // back whatever the provider held at that instant. The timed flush lets every + // microtask that release queued run before the counts are sampled, so the sample is + // the whole of what the mid-open teardown did - anything after it is the release of + // what open() itself completed. + writeToFileTool.clearTaskState(mockCline) + await new Promise((resolve) => { + setTimeout(resolve, 0) + }) + releasesAtOpenReturn = mockCline.diffViewProvider.discardUnapprovedStream.mock.calls.length + resetsAtOpenReturn = mockCline.diffViewProvider.reset.mock.calls.length + }) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + // Nothing is streamed into the cancelled task's view. + expect(mockCline.diffViewProvider.update).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + // And the artifacts the late open() created are cleaned AFTER open() returned: both + // counts grew past what the mid-open teardown left behind, which is what tells the two + // releases apart. + expect(mockCline.diffViewProvider.discardUnapprovedStream.mock.calls.length).toBeGreaterThan( + releasesAtOpenReturn, + ) + expect(mockCline.diffViewProvider.reset.mock.calls.length).toBeGreaterThan(resetsAtOpenReturn) + }) + + it("releases the per-task stream state when provider state rejects during a partial delta", async () => { + // provider.getState() looks like a read and is an await into the extension host. It runs + // after this task's entry and its TaskAborted listener were registered, and a rejection + // here reaches neither the streaming block nor execute()'s teardown - BaseTool.handle() + // only reports the error. Without the outer boundary the singleton keeps the task, its + // diff-view provider and a listener that nothing else removes. + const stateFailure = Object.assign(new Error("EPERM: could not read the extension state"), { + code: "EPERM", + }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + const abortListener = mockCline.once.mock.calls.find( + ([event]: unknown[]) => event === RooCodeEventName.TaskAborted, + )?.[1] + expect(abortListener).toBeInstanceOf(Function) + mockCline.providerRef.deref.mockReturnValue({ getState: vi.fn().mockRejectedValue(stateFailure) }) + // The second delta already streamed and opened the view; only the failing delta matters here. + mockCline.diffViewProvider.open.mockClear() + mockCline.diffViewProvider.discardUnapprovedStream.mockClear() + mockCline.finalizePartialToolAsk.mockClear() + mockHandleError.mockClear() + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortListener) + // Releasing the state must not swallow the failure: BaseTool.handle() still reports it. + expect(mockHandleError).toHaveBeenCalledTimes(1) + expect(mockHandleError).toHaveBeenCalledWith("handling partial write_to_file", stateFailure) + // An earlier delta of THIS stream had already opened the view with unapproved content, so + // releasing the entry has to roll that preview back first: nothing else on this path + // reaches it once the state is gone. No new open happens for the failing delta. + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + expect(mockCline.finalizePartialToolAsk).not.toHaveBeenCalled() + }) + + it("releases the per-task stream state when the filesystem probe rejects during a partial delta", async () => { + // The probe looks like a read and is an await into the filesystem, registered + // after this task's entry and its TaskAborted listener. A rejection here reaches + // neither the streaming block nor execute()'s teardown, so the outer boundary must + // release them and rethrow - the singleton must not keep the task. + const probeFailure = Object.assign(new Error("EPERM: could not probe the target path"), { + code: "EPERM", + }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + const abortListener = mockCline.once.mock.calls.find( + ([event]: unknown[]) => event === RooCodeEventName.TaskAborted, + )?.[1] + expect(abortListener).toBeInstanceOf(Function) + // The earlier deltas set editType from the probe; clear it so the failing delta + // actually reaches fileExistsAtPath() again. + mockCline.diffViewProvider.editType = undefined + mockedFileExistsAtPath.mockRejectedValueOnce(probeFailure) + mockCline.diffViewProvider.open.mockClear() + mockCline.diffViewProvider.discardUnapprovedStream.mockClear() + mockHandleError.mockClear() + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortListener) + // Releasing the state must not swallow the failure: BaseTool.handle() still reports it. + expect(mockHandleError).toHaveBeenCalledTimes(1) + expect(mockHandleError).toHaveBeenCalledWith("handling partial write_to_file", probeFailure) + // Same shape as the state-rejection case above: the earlier delta of this stream opened the + // view, so the release owes it a rollback before the entry goes. + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + }) + + it("does not run a second cleanup when the task aborts while open() is in flight and open() then rejects", async () => { + // openDiffEditor() has command-failure and timeout rejection paths, so a cancellation can + // land while open() is pending and open() can then reject. The TaskAborted teardown already + // released this entry and task disposal already owns the diff cleanup, so the streaming + // catch must stop instead of finalizing the ask and reverting a second time over the same + // view - which would also write the failure mark into an entry that is no longer live. + let abortCleanup: (() => void) | undefined + mockCline.once.mockImplementation((event: RooCodeEventName, listener: () => void) => { + if (event === RooCodeEventName.TaskAborted) { + abortCleanup = listener + } + return mockCline + }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(abortCleanup).toBeInstanceOf(Function) + mockCline.diffViewProvider.open.mockImplementation(async () => { + abortCleanup?.() + throw new Error("command 'vscode.diff' rejected while the task was cancelled") + }) + mockCline.finalizePartialToolAsk.mockClear() + mockCline.diffViewProvider.discardUnapprovedStream.mockClear() + mockCline.diffViewProvider.reset.mockClear() + mockHandleError.mockClear() + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.finalizePartialToolAsk).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + // The cancellation is not a streaming failure: nothing is retained for the next stream, + // and the delta does not report an error the user did not cause. + expect(mockHandleError).not.toHaveBeenCalled() + }) + + it("stops before the diff restore when the task aborts while the failed ask is being finalized", async () => { + // The cleanup has two awaits. A cancellation that lands in the gap between them has + // already run the teardown, and task disposal owns the diff cleanup from that moment, so + // restoring and resetting here would race the disposal over the same view. + let abortCleanup: (() => void) | undefined + mockCline.once.mockImplementation((event: RooCodeEventName, listener: () => void) => { + if (event === RooCodeEventName.TaskAborted) { + abortCleanup = listener + } + return mockCline + }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(abortCleanup).toBeInstanceOf(Function) + mockCline.diffViewProvider.open.mockRejectedValue(new Error("command 'vscode.diff' rejected")) + mockCline.finalizePartialToolAsk.mockImplementation(async () => { + abortCleanup?.() + }) + mockCline.diffViewProvider.discardUnapprovedStream.mockClear() + mockCline.diffViewProvider.reset.mockClear() + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + // The first cleanup step ran; the second must not. + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + }) + + it("does not treat a changed path between deltas as stabilized", async () => { + // Delta 1 streams "alpha.txt"; delta 2 streams "beta.txt" for the same task. The path changed + // between deltas, so it must not count as stabilized and no partial `tool` ask may be issued for + // the still-changing second path. + await executeWriteFileTool({ path: "alpha.txt" }, { isPartial: true }) + await executeWriteFileTool({ path: "beta.txt" }, { isPartial: true }) + + expect(mockCline.ask).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + }) + + it("does not issue a partial ask when content is undefined after path stabilization", async () => { + // Delta 1 stabilizes the path. Delta 2 repeats it but carries no content yet: the + // `newContent === undefined` clause must short-circuit the ask even though the path itself has + // stabilized. + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({ content: undefined }, { isPartial: true }) + + expect(mockCline.ask).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.update).not.toHaveBeenCalled() + }) + + it("does not reopen an already open diff view during streaming", async () => { + // The diff view is already open for this task (isEditing). A stabilized delta must still update + // the streamed content but must not call open() again -- reopening would discard the view's + // current state. + mockCline.diffViewProvider.isEditing = true + + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({}, { isPartial: true }) + + expect(mockCline.ask).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.update).toHaveBeenCalledWith(testContent, false) + }) + + it("logs the streaming diff view failure with the write_to_file context", async () => { + // The catch arm logs a context-specific message before swallowing the error (execute() reports + // the authoritative one). The message must keep the write_to_file context so the log is + // actionable. + mockCline.diffViewProvider.open.mockRejectedValue(new Error("EACCES: permission denied")) + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({}, { isPartial: true }) + + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error streaming write_to_file diff view:", + expect.anything(), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("reports the captured streaming error instead of the parse error when the final block fails to parse, and clears the per-task state", async () => { + // A streaming delta fails with a filesystem error (streamFailed + streamError are + // captured). The final block then arrives without nativeArgs, so execute() never + // runs: the parse-failure teardown boundary must report the original filesystem + // error under the "writing file" context (not the incidental parse error) and tear + // down the per-task state, so the next write_to_file stream in this task is not + // blocked by the stale streamFailed guard and no abort listener leaks. + const fsError = new Error("EACCES: permission denied") + mockCline.diffViewProvider.open.mockRejectedValue(fsError) + // Capture the abort listener of the state created by the first deltas: it is the + // exact reference that the parse-failure teardown must detach. + let abortListener: (() => void) | undefined + mockCline.once.mockImplementation((event: RooCodeEventName, listener: () => void) => { + if (event === RooCodeEventName.TaskAborted && abortListener === undefined) { + abortListener = listener + } + return mockCline + }) + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({}, { isPartial: true }) + + const toolUse: ToolUse = { + type: "tool_use", + name: "write_to_file", + params: { path: testFilePath, content: testContent }, + nativeArgs: undefined, + partial: false, + } + await writeToFileTool.handle(mockCline, toolUse as ToolUse<"write_to_file">, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult: vi.fn(), + toolCallId: "test-tool-call-id", + }) + + expect(mockHandleError).toHaveBeenCalledTimes(1) + expect(mockHandleError).toHaveBeenCalledWith("writing file", fsError) + expect(mockHandleError).not.toHaveBeenCalledWith( + expect.stringContaining("parsing write_to_file"), + expect.anything(), + ) + // The parse-failure teardown also restores the diff document: the + // streaming failure above already reverted it once (revert + reset), + // and the parse path runs the same cleanup again because execute() + // never runs on this path. + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(2) + expect(mockCline.diffViewProvider.reset).toHaveBeenCalledTimes(2) + // Per-task state torn down at this boundary: guard cleared, the exact + // registered abort listener detached. + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect(abortListener).toBeTypeOf("function") + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortListener) + + // The next stream for the same task must issue a partial ask again (the stale + // streamFailed guard is gone). + mockCline.diffViewProvider.open.mockResolvedValue(undefined) + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({}, { isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(2) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("restores the diff document when the final block fails to parse after successful streaming", async () => { + // Streaming opened the diff view with unapproved partial content (open and + // update both succeeded, so no streaming error was captured). The final block + // then arrives without nativeArgs: execute() never runs, so its error cleanup + // never fires. The parse-failure teardown must still restore the document + // (revert before reset) or a user save could persist content the write never + // completed, and must report the generic parse error (no streaming error to + // surface instead). + let abortListener: (() => void) | undefined + mockCline.once.mockImplementation((event: RooCodeEventName, listener: () => void) => { + if (event === RooCodeEventName.TaskAborted && abortListener === undefined) { + abortListener = listener + } + return mockCline + }) + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + // Delta 1 - stabilize path; delta 2 - streams the partial content into the + // diff view (open + update resolve). + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({}, { isPartial: true }) + expect(mockCline.diffViewProvider.open).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.update).toHaveBeenCalledTimes(1) + + const toolUse: ToolUse = { + type: "tool_use", + name: "write_to_file", + params: { path: testFilePath, content: testContent }, + nativeArgs: undefined, + partial: false, + } + await writeToFileTool.handle(mockCline, toolUse as ToolUse<"write_to_file">, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult: vi.fn(), + toolCallId: "test-tool-call-id", + }) + + // No streaming error was captured: the generic parse error is reported. + expect(mockHandleError).toHaveBeenCalledTimes(1) + expect(mockHandleError).toHaveBeenCalledWith("parsing write_to_file args", expect.any(Error)) + // The diff document is restored by the parse path itself (no streaming + // failure happened, so this is the only revert + reset in the test). + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.reset).toHaveBeenCalledTimes(1) + // Per-task state torn down: guard cleared, exact listener detached. + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect(abortListener).toBeTypeOf("function") + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortListener) + } finally { + consoleErrorSpy.mockRestore() + } + }) + }) + + describe("path stabilization predicate", () => { + // The predicate is exercised directly (it is private) because not all of its branches are + // observable through handlePartial(): an undefined path reaches the same early return either + // way, so the clause-by-clause behavior must be pinned at the predicate level. + function makeState(lastSeenPartialPath: string | undefined) { + return { + lastSeenPartialPath, + streamFailed: false, + differentPathStream: false, + // A hand-built state never reached the diff view; the flag is what the cleanup sites read. + ownsPreview: false, + streamError: undefined, + task: mockCline, + abortCleanup: () => {}, + } + } + + it("reports a first delta as not stabilized and records the seen path", () => { + const state = makeState(undefined) + + expect(writeToFileTool["hasPathStabilizedForTask"](state, "a.txt")).toBe(false) + expect(state.lastSeenPartialPath).toBe("a.txt") + }) + + it("reports a repeated path as stabilized", () => { + const state = makeState("a.txt") + + expect(writeToFileTool["hasPathStabilizedForTask"](state, "a.txt")).toBe(true) + }) + + it("reports a changed path as not stabilized", () => { + const state = makeState("a.txt") + + expect(writeToFileTool["hasPathStabilizedForTask"](state, "b.txt")).toBe(false) + expect(state.lastSeenPartialPath).toBe("b.txt") + }) + }) + + describe("resetPartialState", () => { + it("resets the base partial path and detaches every task's abort listener", async () => { + let abortCleanup: (() => void) | undefined + mockCline.once.mockImplementation((event: RooCodeEventName, listener: () => void) => { + if (event === RooCodeEventName.TaskAborted) { + abortCleanup = listener + } + return mockCline + }) + + // Seed one per-task state with an abort listener attached. + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({}, { isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(1) + expect(abortCleanup).toBeTypeOf("function") + + // The base-class singleton field is reset by super.resetPartialState(). + writeToFileTool["lastSeenPartialPath"] = "stale-path" + writeToFileTool.resetPartialState() + + expect(writeToFileTool["lastSeenPartialPath"]).toBeUndefined() + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortCleanup) + + // The per-task map was cleared too: a fresh delta sequence starts un-stabilized, so no + // second partial ask is issued. + await executeWriteFileTool({}, { isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(1) + }) + }) + + describe("early-exit stream state cleanup", () => { + it("releases the per-task stream state when a rooignore denial returns early", async () => { + // A partial delta creates the per-task state and registers the abort listener; the + // denial then returns before the cleanup, which used to leave both behind for the + // task's lifetime (a retained streamFailed also suppresses later diff previews). + await executeWriteFileTool({}, { isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + + await executeWriteFileTool({}, { accessAllowed: false }) + + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + // The teardown has to detach the function this tool registered; expect.any(Function) + // also passes when a different callback is removed and the real one keeps firing. + const abortListener = mockCline.once.mock.calls.find( + ([event]: unknown[]) => event === RooCodeEventName.TaskAborted, + )?.[1] + expect(abortListener).toBeInstanceOf(Function) + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortListener) + }) + + it("releases the per-task stream state when a missing parameter returns early", async () => { + await executeWriteFileTool({}, { isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + + await writeToFileTool.execute({ path: "", content: "mock content" }, mockCline, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + toolCallId: "test-tool-call-id", + }) + + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + // This call's stream only ever reached the missing-parameter return, so it never opened the + // diff view: the early return must leave the provider alone, because reset() there + // clears relPath/isEditing - which is what a session retained by an earlier call needs + // to survive - and forgets whose placeholder the empty file is. The per-task bookkeeping + // is released above regardless. + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + }) + + it("releases the per-task stream state when content is missing", async () => { + // The missing-content return sits before execute()'s guarded scope, so it needs its own + // release. The state is seeded first so the assertion proves a release happened rather + // than an empty map. + writeToFileTool["getTaskPartialStreamState"](mockCline as never) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + + const toolUse = { + type: "tool_use", + name: "write_to_file", + params: { path: testFilePath }, + nativeArgs: { path: testFilePath, content: undefined }, + // The fixture's point is a nativeArgs object whose content never arrived, which the + // typed params cannot express - hence the double assertion. + partial: false, + } as unknown as ToolUse<"write_to_file"> + const pushToolResult = vi.fn() + await writeToFileTool.handle(mockCline, toolUse, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult, + toolCallId: "test-tool-call-id", + }) + + expect(mockCline.sayAndCreateMissingParamError).toHaveBeenCalledWith("write_to_file", "content") + expect(pushToolResult).toHaveBeenCalledWith("Missing param error") + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + const abortListener = mockCline.once.mock.calls.find( + ([event]: unknown[]) => event === RooCodeEventName.TaskAborted, + )?.[1] + expect(abortListener).toBeInstanceOf(Function) + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortListener) + // This call's stream only ever reached the missing-parameter return, so it never opened the + // diff view: the early return must leave the provider alone, because reset() there + // clears relPath/isEditing - which is what a session retained by an earlier call needs to + // survive - and forgets whose placeholder the empty file is. The per-task bookkeeping is + // released above regardless. + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + }) + + it("discards the streamed preview when a rooignore denial returns early", async () => { + // The denial can arrive after a streaming delta opened the denied path and streamed + // content into it. This branch reported the denial and released the stream state, but + // never touched the diff view: the unapproved content sat in a saveable editor, and the + // provider kept this call's editType/relPath for whatever write came next. + // The first delta only records the path in hasPathStabilizedForTask(); it takes a second matching + // delta before open()/update() run. Without a streamed preview this test would check cleanup calls + // against a diff view that was never opened, so stream it first and pin its order before the denial. + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({}, { isPartial: true }) + + expect(mockCline.diffViewProvider.open).toHaveBeenCalled() + expect(mockCline.diffViewProvider.update).toHaveBeenCalled() + + await executeWriteFileTool({}, { accessAllowed: false }) + + expect(mockCline.say).toHaveBeenCalledWith("rooignore_error", testFilePath) + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + // The streamed preview above is what the denial cleanup has to run after. + expect(mockCline.diffViewProvider.open.mock.invocationCallOrder[0]).toBeLessThan( + mockCline.diffViewProvider.discardUnapprovedStream.mock.invocationCallOrder[0], + ) + expect(mockCline.diffViewProvider.discardUnapprovedStream.mock.invocationCallOrder[0]).toBeLessThan( + mockCline.diffViewProvider.reset.mock.invocationCallOrder[0], + ) + expect(mockCline.diffViewProvider.reset).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.saveChanges).not.toHaveBeenCalled() + }) + }) + + it("leaves a retained session untouched when a parameter is missing and this stream never reached the view", async () => { + // The state entry is seeded by hand because the case the ownership guard exists for is a + // provider session that an EARLIER call left retained (a rollback that could not complete + // keeps relPath/isEditing and the placeholder ownership) while this call's own stream + // never opened the view. Discarding or resetting that provider state here would throw the + // retained session away, so the early return must not touch it. + writeToFileTool["getTaskPartialStreamState"](mockCline as never) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + + const toolUse = { + type: "tool_use", + name: "write_to_file", + params: { path: testFilePath }, + nativeArgs: { path: testFilePath, content: undefined }, + // The fixture's point is a nativeArgs object whose content never arrived, which the typed + // params cannot express - hence the double assertion. + partial: false, + } as unknown as ToolUse<"write_to_file"> + const pushToolResult = vi.fn() + await writeToFileTool.handle(mockCline, toolUse, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult, + toolCallId: "test-tool-call-id", + }) + + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + }) + + it("still discards the preview this stream opened when a parameter is missing", async () => { + // The counterpart of the case above: two deltas of one path do reach the diff view, so the + // missing-content return owes that unapproved preview a rollback before it releases the + // state - the ownership guard must not skip a teardown this stream actually earned. + await executeWriteFileTool({}, { isPartial: true }) + await executeWriteFileTool({}, { isPartial: true }) + expect(mockCline.diffViewProvider.open).toHaveBeenCalledTimes(1) + mockCline.diffViewProvider.discardUnapprovedStream.mockClear() + mockCline.diffViewProvider.reset.mockClear() + + const toolUse = { + type: "tool_use", + name: "write_to_file", + params: { path: testFilePath }, + nativeArgs: { path: testFilePath, content: undefined }, + // The fixture's point is a nativeArgs object whose content never arrived, which the typed + // params cannot express - hence the double assertion. + partial: false, + } as unknown as ToolUse<"write_to_file"> + const pushToolResult = vi.fn() + await writeToFileTool.handle(mockCline, toolUse, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult, + toolCallId: "test-tool-call-id", + }) + + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.discardUnapprovedStream.mock.invocationCallOrder[0]).toBeLessThan( + mockCline.diffViewProvider.reset.mock.invocationCallOrder[0], + ) + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() }) describe("user interaction", () => { @@ -461,16 +1310,860 @@ describe("writeToFileTool", () => { expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() }) - it("handles partial streaming errors after path stabilizes", async () => { + it("swallows partial streaming errors instead of surfacing a duplicate error bubble", async () => { + // The same filesystem operation is retried in execute() once the block completes, + // and that authoritative non-partial path reports the error to the user. Surfacing + // it during streaming too would show the same error twice, so handlePartial must NOT + // route streaming errors through handleError. mockCline.diffViewProvider.open.mockRejectedValue(new Error("Open failed")) // First call - path not yet stabilized, no error yet await executeWriteFileTool({}, { isPartial: true }) expect(mockHandleError).not.toHaveBeenCalled() - // Second call with same path - path is now stabilized, error occurs + // Second call with same path - path is now stabilized, error occurs but is swallowed await executeWriteFileTool({}, { isPartial: true }) - expect(mockHandleError).toHaveBeenCalledWith("handling partial write_to_file", expect.any(Error)) + expect(mockHandleError).not.toHaveBeenCalled() + }) + + it("finalizes partial tool message and resets diff view when handlePartial open() fails", async () => { + // Regression test: when diffViewProvider.open() throws during streaming (e.g. EACCES/EROFS + // on a read-only path), the partial tool ask created at the top of handlePartial leaves the + // UI spinner stuck. handlePartial must finalize the partial message and reset the diff view, + // and must NOT surface a duplicate error (execute() reports the authoritative one). + mockCline.diffViewProvider.open.mockRejectedValue( + Object.assign(new Error("EACCES: permission denied, open '/ro/test.py'"), { code: "EACCES" }), + ) + // Record the relative order of discardUnapprovedStream() and reset() (vitest mocks expose + // no invocationCallOrder). + const diffViewCallOrder: string[] = [] + mockCline.diffViewProvider.discardUnapprovedStream.mockImplementation(async () => { + diffViewCallOrder.push("revert") + }) + mockCline.diffViewProvider.reset.mockImplementation(async () => { + diffViewCallOrder.push("reset") + }) + + // First call - path not yet stabilized + await executeWriteFileTool({}, { isPartial: true }) + expect(mockCline.finalizePartialToolAsk).not.toHaveBeenCalled() + + // Second call - path stabilized, open() rejects + await executeWriteFileTool({}, { isPartial: true }) + + // Exact streamed payload: finalizePartialToolAsk() no-ops on a text mismatch, so + // a wrong argument (e.g. relPath) would leave the spinner stuck. + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith(expectedPartialToolMessage) + // The failed write's streamed content must be reverted before reset() clears the + // state discardUnapprovedStream() relies on. + expect(diffViewCallOrder).toEqual(["revert", "reset"]) + expect(mockHandleError).not.toHaveBeenCalled() + }) + + it("finalizes partial tool message and resets diff view when handlePartial update() fails", async () => { + // Same regression as above but for the streaming update() call failing after open() succeeds. + mockCline.diffViewProvider.update.mockRejectedValue( + Object.assign(new Error("EROFS: read-only file system, write '/ro/test.py'"), { code: "EROFS" }), + ) + // Record the relative order of discardUnapprovedStream() and reset() (vitest mocks expose + // no invocationCallOrder). + const diffViewCallOrder: string[] = [] + mockCline.diffViewProvider.discardUnapprovedStream.mockImplementation(async () => { + diffViewCallOrder.push("revert") + }) + mockCline.diffViewProvider.reset.mockImplementation(async () => { + diffViewCallOrder.push("reset") + }) + + // First call - path not yet stabilized + await executeWriteFileTool({}, { isPartial: true }) + + // Second call - path stabilized, update() rejects + await executeWriteFileTool({}, { isPartial: true }) + + // Exact streamed payload: finalizePartialToolAsk() no-ops on a text mismatch, so + // a wrong argument (e.g. relPath) would leave the spinner stuck. + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith(expectedPartialToolMessage) + // The failed write's streamed content must be reverted before reset() clears the + // state discardUnapprovedStream() relies on. + expect(diffViewCallOrder).toEqual(["revert", "reset"]) + expect(mockHandleError).not.toHaveBeenCalled() + }) + + it("does not spawn a new partial tool message on each streaming delta after a failure", async () => { + // Regression test: after diffViewProvider.open() throws and the partial message is + // finalized + diff view reset, the next streaming delta saw a non-partial last message + // and created a brand new "Zoo wants to edit this file" message -- repeating once per + // delta. After the fix, partialStreamFailed short-circuits subsequent deltas so only + // the single initial partial ask is issued. + mockCline.diffViewProvider.open.mockRejectedValue( + Object.assign(new Error("EROFS: read-only file system, mkdir '/scratch'"), { code: "EROFS" }), + ) + + // Delta 1 - stabilize path (no ask yet) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + // Delta 2 - path stabilized, ask issued once, open() fails, stream marked failed + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + // Deltas 3..5 - must be short-circuited, no further asks + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + // Only the single partial ask from delta 2 should have been issued + expect(mockCline.ask).toHaveBeenCalledTimes(1) + // open() must not be retried after the first failure + expect(mockCline.diffViewProvider.open).toHaveBeenCalledTimes(1) + }) + + it("finalizes any open partial tool ask when final args cannot be parsed", async () => { + // Regression test: a write_to_file block whose final args fail to parse (e.g. the + // tool call was truncated mid-JSON by the output token limit) never reaches + // execute(). A streaming delta for that block may already have opened a partial + // `tool` ask (partial: true) -- BaseTool.handle must finalize it, otherwise the + // UI spinner stays stuck even though the parse error bubble was shown. + // Delta 1 - stabilize path (no ask yet) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + // Delta 2 - path stabilized, partial ask issued once + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(1) + expect(mockCline.finalizePartialToolAsk).not.toHaveBeenCalled() + + // Final block arrives but its native args cannot be parsed, so execute() is skipped. + const toolUse: ToolUse = { + type: "tool_use", + name: "write_to_file", + params: { + path: testFilePath, + content: testContent, + }, + partial: false, + } + await writeToFileTool.handle(mockCline, toolUse as ToolUse<"write_to_file">, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + toolCallId: "test-tool-call-id", + }) + + // The parse error is still reported, and the open partial ask is finalized first. + // No argument: BaseTool.handle() calls finalizePartialToolAsk() with no text, so a + // mutation passing wrong text would leave findLast() unmatched and the spinner + // stuck. (toHaveBeenCalledWith(undefined) does not match a no-arg call under + // vitest's matcher semantics: [] is not equal to [undefined].) + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledTimes(1) + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith() + expect(mockHandleError).toHaveBeenCalledWith("parsing write_to_file args", expect.any(Error)) + }) + + it("continues parse failure cleanup when finalizing the partial ask fails", async () => { + // Pins the .catch arm on task.finalizePartialToolAsk() in BaseTool.handle(): when the + // final args cannot be parsed and finalizing the open partial ask also fails, the + // failure must only be logged so the parse error is still reported to the user. + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + mockCline.finalizePartialToolAsk.mockRejectedValue(new Error("finalize failed")) + + // Final block arrives but its native args cannot be parsed, so execute() is skipped. + const toolUse: ToolUse = { + type: "tool_use", + name: "write_to_file", + params: { + path: testFilePath, + content: testContent, + }, + partial: false, + } + await writeToFileTool.handle(mockCline, toolUse as ToolUse<"write_to_file">, { + askApproval: mockAskApproval, + handleError: mockHandleError, + pushToolResult: vi.fn(), + toolCallId: "test-tool-call-id", + }) + + // Same no-argument contract as the sibling test above: the finalize call in + // BaseTool.handle() carries no text. + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledTimes(1) + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith() + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error finalizing write_to_file partial tool ask:", + expect.any(Error), + ) + // The parse error is still reported despite the failed finalization. + expect(mockHandleError).toHaveBeenCalledWith("parsing write_to_file args", expect.any(Error)) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("reports a filesystem error only once across the streaming and execute phases", async () => { + // Regression test for the double-error UX defect: a single write_to_file call to a + // read-only path failed twice -- once in handlePartial ("handling partial write_to_file") + // and once in execute() ("writing file"). handlePartial now swallows its error so only + // the authoritative execute() error is surfaced. + const erofs = () => + Object.assign(new Error("EROFS: read-only file system, mkdir '/scratch'"), { code: "EROFS" }) + mockCline.diffViewProvider.open.mockRejectedValue(erofs()) + mockedCreateDirectoriesForFile.mockRejectedValue(erofs()) + + // Streaming phase: stabilize path then fail (swallowed, no handleError) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + // Final phase: execute() reports the single authoritative error + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledTimes(1) + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + }) + + it("does not reset consecutive mistake count when directory creation fails", async () => { + mockCline.consecutiveMistakeCount = 3 + mockedCreateDirectoriesForFile.mockRejectedValue( + Object.assign(new Error("EACCES: permission denied, mkdir '/ro'"), { code: "EACCES" }), + ) + + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.consecutiveMistakeCount).toBe(3) + }) + + it("reverts the diff document when the write fails before approval", async () => { + // Regression test for the dirty-diff leak: streaming already opened the diff view + // with unapproved content, and the write then failed before the user could approve + // it. reset() alone left the diff document dirty with the streamed content -- a + // user save in the editor would persist a write the task never completed. The + // error path must revert the document (like the approval-denied path does) before + // resetting the provider state. + mockedCreateDirectoriesForFile.mockRejectedValue( + Object.assign(new Error("EACCES: permission denied, mkdir '/ro'"), { code: "EACCES" }), + ) + // Record the relative order of discardUnapprovedStream() and reset() (vitest mocks expose + // no invocationCallOrder). + const diffViewCallOrder: string[] = [] + mockCline.diffViewProvider.discardUnapprovedStream.mockImplementation(async () => { + diffViewCallOrder.push("revert") + }) + mockCline.diffViewProvider.reset.mockImplementation(async () => { + diffViewCallOrder.push("reset") + }) + + // Stream two deltas so the diff view is open with the unapproved content... + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + // ...then the completed block fails before approval + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(diffViewCallOrder).toEqual(["revert", "reset"]) + }) + + it("continues cleanup when reverting the diff document fails before approval", async () => { + // Pins the .catch arm on discardUnapprovedStream() in discardUnapprovedStreamBeforeReset(): a failed + // revert (e.g. the diff view was already closed) must only be logged so the + // remaining cleanup (diff view reset + per-task state teardown) always completes. + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + let abortCleanup: (() => void) | undefined + mockCline.once.mockImplementation((event: RooCodeEventName, listener: () => void) => { + if (event === RooCodeEventName.TaskAborted) { + abortCleanup = listener + } + return mockCline + }) + mockedCreateDirectoriesForFile.mockRejectedValue( + Object.assign(new Error("EACCES: permission denied, mkdir '/ro'"), { code: "EACCES" }), + ) + mockCline.diffViewProvider.discardUnapprovedStream.mockRejectedValue(new Error("revert failed")) + + // Stream two deltas so the diff view opens with the unapproved content... + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + // ...then the completed block fails before approval and the revert fails too. + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error discarding the unapproved write_to_file diff view:", + expect.any(Error), + ) + // The diff view is still reset and the per-task stream state still torn down. + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + // The reference that was registered must be the one removed. + expect(abortCleanup).toBeTypeOf("function") + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortCleanup) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("keeps approved diff content in the editor when saving fails after approval", async () => { + // The reverse of the previous test: once the user approved the write, the diff + // content is their accepted edit. A late failure (e.g. saveChanges rejecting) + // must NOT revert it -- the document stays dirty so the user can save it manually. + mockCline.diffViewProvider.saveChanges.mockRejectedValueOnce(new Error("save failed")) + + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.saveChanges).toHaveBeenCalled() + // The error path restores through discardUnapprovedStream(), not revertChanges(), so the + // discard is the call that would have thrown the approved edit away. + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + }) + + it("does not roll back a write whose commit point has already passed", async () => { + // saveChanges() signals the commit point at the document save and then keeps working + // (closing the diff views, tab bookkeeping, diagnostics). A rejection in that tail is a + // failure AFTER a durable write: rolling back here would restore the previous content or + // delete a file the user had just approved being created. + let signalledAtTheSave = false + mockCline.diffViewProvider.saveChanges.mockImplementationOnce(async (...args: unknown[]) => { + const onCommit = args[2] as (() => void) | undefined + signalledAtTheSave = typeof onCommit === "function" + onCommit?.() + throw new Error("closeAllDiffViews rejected") + }) + + await executeWriteFileTool({}, { fileExists: false }) + + // The stand-down only works if execute() actually handed saveChanges() the signal. + expect(signalledAtTheSave).toBe(true) + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + }) + + it("removes the owned placeholder when saveChanges fails before the commit point", async () => { + // save() resolving false makes saveChanges() throw before onCommit: approval is not + // persistence. The tool must not report success, and the empty placeholder open() + // created must be removed while it is still owned - reset() would otherwise strand + // it unowned for a later attempt to mistake for the pre-existing target. + const order: string[] = [] + mockCline.diffViewProvider.saveChanges.mockImplementationOnce(async () => { + throw new Error("Saving /test/path.txt was not confirmed; the write was not committed.") + }) + mockCline.diffViewProvider.discardOwnedPlaceholder = vi.fn(async () => { + order.push("discardPlaceholder") + }) + mockCline.diffViewProvider.reset = vi.fn(async () => { + order.push("reset") + }) + + await executeWriteFileTool({}, { fileExists: false }) + + // No success: the failure reaches handleError, not a write result. + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.pushToolWriteResult).not.toHaveBeenCalled() + // The approved content stays in the editor (no discard of the buffer), but the + // owned placeholder is removed BEFORE reset() clears the ownership. + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.discardOwnedPlaceholder).toHaveBeenCalledTimes(1) + expect(order).toEqual(["discardPlaceholder", "reset"]) + }) + + it("reports the stranded placeholder and skips the reset when its removal fails", async () => { + // Pre-commit save failure followed by an EPERM placeholder removal: the hazard + // must reach the user, and reset() must not run - it would clear the ownership + // and strand the empty placeholder unowned with no retry path. + mockCline.diffViewProvider.saveChanges.mockImplementationOnce(async () => { + throw new Error("Saving /test/path.txt was not confirmed; the write was not committed.") + }) + mockCline.diffViewProvider.discardOwnedPlaceholder = vi + .fn() + .mockRejectedValue(Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" })) + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + try { + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.pushToolWriteResult).not.toHaveBeenCalled() + // The hazard is user-visible, not only a console line... + expect(mockCline.say).toHaveBeenCalledWith("error", expect.stringContaining("placeholder")) + // ...and ownership survives: reset() did not run to forget it. + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error removing the uncommitted write_to_file placeholder:", + expect.any(Error), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("keeps the placeholder owned and skips the reset when a denied new-file rollback cannot remove it", async () => { + // A denial rolls the new file back; if the rollback cannot remove the placeholder + // (refused restore, EPERM unlink) the provider still owns it. reset() would forget + // that ownership and strand the empty file unowned, so it must be skipped and the + // hazard reported - the same discipline as the pre-commit save-failure path. + mockAskApproval.mockResolvedValue(false) + mockCline.diffViewProvider.revertChanges = vi + .fn() + .mockRejectedValue(Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" })) + mockCline.diffViewProvider.discardUnapprovedStream = vi + .fn() + .mockRejectedValue(Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" })) + // The rollback left the placeholder on disk: the provider still owns it. + mockCline.diffViewProvider.ownsPlaceholder = true + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + try { + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + // Ownership survives: reset() did not run to forget it... + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + // ...and the hazard is user-visible, not only a console line. + expect(mockCline.say).toHaveBeenCalledWith("error", expect.stringContaining("placeholder")) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("keeps the session unreset when the denied rollback cannot confirm the placeholder save", async () => { + // A refused document.save() (resolves false) is a rollback failure, not a success: + // both rollback helpers stop with the placeholder still owned, so reset() must be + // skipped - it would forget the ownership and leave the dirty buffer one save away + // from recreating the denied file - and the hazard must be reported. + mockAskApproval.mockResolvedValue(false) + mockCline.diffViewProvider.revertChanges = vi + .fn() + .mockRejectedValue( + new Error( + "Rollback could not save the restored buffer for test/path.txt; its clean state is unconfirmed.", + ), + ) + mockCline.diffViewProvider.discardUnapprovedStream = vi + .fn() + .mockRejectedValue( + new Error( + "Rollback could not save the restored buffer for test/path.txt; its clean state is unconfirmed, so the cleanup stopped before closing tabs or deleting the placeholder.", + ), + ) + // The refused save left the placeholder on disk: the provider still owns it. + mockCline.diffViewProvider.ownsPlaceholder = true + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + try { + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + // Ownership survives: reset() did not run to forget it... + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + // ...the rollback hazard and the stranded placeholder are both user-visible: + // assert each report separately, so dropping one cannot hide behind the other. + expect(mockCline.say).toHaveBeenCalledWith("error", expect.stringContaining("placeholder")) + expect(mockCline.say).toHaveBeenCalledWith( + "error", + expect.stringContaining("could not be restored after the failed tool call"), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("rejects a write for a different path while a session is retained", async () => { + // A refused rollback keeps isEditing + the dirty buffer for a retry of ITS + // path. Writing a different path through that session would update and save + // the old document while asking approval for the new one, so the call is + // rejected before any cleanup which could reset the retained session. + // Drive the decision off the production predicate rather than a hand-rolled stub: this is + // a real DiffViewProvider carrying the state a refused rollback leaves behind (isEditing + // + relPath), so the class under test is what decides whether the session is in the way. + const retainedSession: Pick = Object.assign( + Object.create(DiffViewProvider.prototype), + { isEditing: true, relPath: "test/path.txt" }, + ) + mockCline.diffViewProvider.isEditingDifferentPath = (relPath: string) => + retainedSession.isEditingDifferentPath(relPath) + mockCline.diffViewProvider.editingRelPath = "test/path.txt" + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + try { + await executeWriteFileTool({ path: "other/path.txt" }, { fileExists: false }) + + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.update).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.saveChanges).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + expect(mockCline.say).toHaveBeenCalledWith( + "error", + expect.stringContaining("unfinished write to 'test/path.txt' must be resolved first"), + ) + // The remedy must name the only path that actually releases the session. + expect(mockCline.say).toHaveBeenCalledWith( + "error", + expect.stringContaining("Retry the write to 'test/path.txt'"), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("still completes the teardown when the stranded-placeholder report itself rejects", async () => { + // The hazard report must not abort the cleanup: a failing say is logged and the + // error path completes - the session stays unreset so the placeholder ownership + // survives for a retry. + mockCline.diffViewProvider.saveChanges.mockImplementationOnce(async () => { + throw new Error("Saving /test/path.txt was not confirmed; the write was not committed.") + }) + mockCline.diffViewProvider.discardOwnedPlaceholder = vi + .fn() + .mockRejectedValue(Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" })) + mockCline.say = vi.fn().mockRejectedValue(new Error("webview is gone")) + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + try { + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error reporting write_to_file stranded placeholder failure:", + expect.any(Error), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("continues execute error cleanup when finalizing partial ask fails", async () => { + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + mockedCreateDirectoriesForFile.mockRejectedValue( + Object.assign(new Error("EACCES: permission denied, mkdir '/ro'"), { code: "EACCES" }), + ) + mockCline.finalizePartialToolAsk.mockRejectedValue(new Error("finalize failed")) + + await executeWriteFileTool({}, { fileExists: false }) + + // The execute error path finalizes without a text match: any open partial + // tool ask is closed. + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith(undefined) + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error finalizing write_to_file partial tool ask:", + expect.any(Error), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("keeps partial stream failures isolated per task", async () => { + mockCline.diffViewProvider.open.mockRejectedValueOnce( + Object.assign(new Error("EROFS: read-only file system, mkdir '/task-a'"), { code: "EROFS" }), + ) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(1) + + mockCline.taskId = "task-2" + mockCline.instanceId = "instance-2" + mockCline.diffViewProvider.open.mockResolvedValue(undefined) + mockCline.diffViewProvider.update.mockResolvedValue(undefined) + mockCline.diffViewProvider.editType = undefined + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockCline.ask).toHaveBeenCalledTimes(1) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.ask).toHaveBeenCalledTimes(2) + expect(mockCline.diffViewProvider.open).toHaveBeenCalledTimes(2) + }) + + it("swallows diff view reset errors during partial failure cleanup", async () => { + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + mockCline.diffViewProvider.open.mockRejectedValue( + Object.assign(new Error("EROFS: read-only file system, mkdir '/scratch'"), { code: "EROFS" }), + ) + mockCline.diffViewProvider.reset.mockRejectedValue(new Error("reset failed")) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith(expectedPartialToolMessage) + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + expect(mockHandleError).not.toHaveBeenCalled() + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error resetting write_to_file diff view:", + expect.any(Error), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("continues partial failure cleanup when finalizing partial ask fails", async () => { + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + mockCline.diffViewProvider.open.mockRejectedValue( + Object.assign(new Error("EROFS: read-only file system, mkdir '/scratch'"), { code: "EROFS" }), + ) + mockCline.finalizePartialToolAsk.mockRejectedValue(new Error("finalize failed")) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith(expectedPartialToolMessage) + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + expect(mockHandleError).not.toHaveBeenCalled() + expect(consoleErrorSpy).toHaveBeenCalledWith( + "Error finalizing write_to_file partial tool ask:", + expect.any(Error), + ) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("EROFS in handlePartial does not stall agent loop -- createDirectoriesForFile is not called", async () => { + // Regression test: before the fix, createDirectoriesForFile was called in handlePartial + // with no .catch() guard. An EROFS throw escaped to BaseTool.handle(), which called + // handleError but did not set didRejectTool/didAlreadyUseTool, so the advancement gate + // in presentAssistantMessage was never reached and the agent loop stalled permanently. + // After the fix the call is removed entirely -- handlePartial never touches the filesystem. + mockedCreateDirectoriesForFile.mockRejectedValue( + Object.assign(new Error("EROFS: read-only file system, mkdir '/scratch'"), { code: "EROFS" }), + ) + + // First call -- path not yet stabilized, returns early + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockHandleError).not.toHaveBeenCalled() + + // Second call -- path stabilized; createDirectoriesForFile must NOT be called from + // handlePartial, so the mock rejection must not trigger and handleError must not be called + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(mockedCreateDirectoriesForFile).not.toHaveBeenCalled() + expect(mockHandleError).not.toHaveBeenCalled() + }) + + it("EROFS in execute() routes through handleError with cleanup rather than escaping unhandled", async () => { + // Regression test: before the fix, createDirectoriesForFile in execute() sat outside + // the try block (lines 70-74), so an EROFS error escaped the catch at line 188 entirely. + // After the fix the call is inside the try block, so filesystem errors are caught and + // routed through handleError with proper diffViewProvider.reset() cleanup. + mockedCreateDirectoriesForFile.mockRejectedValue( + Object.assign(new Error("EROFS: read-only file system, mkdir '/scratch'"), { code: "EROFS" }), + ) + + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + // The tool must not have proceeded to open or save + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.saveChanges).not.toHaveBeenCalled() + }) + + it("finalizes partial tool message on error so the UI spinner does not get stuck", async () => { + // Regression test: when a filesystem error is thrown in execute() the webview + // message created during handlePartial (or the early ask in execute) is stuck in + // partial: true state, showing an indefinite spinner alongside the error bubble. + // The catch block must call finalizePartialToolAsk() to close the spinner without + // blocking for user input. + mockedCreateDirectoriesForFile.mockRejectedValue( + Object.assign(new Error("EACCES: permission denied, mkdir '/ro'"), { code: "EACCES" }), + ) + + await executeWriteFileTool({}, { fileExists: false }) + + // handleError must still be called + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + + // finalizePartialToolAsk must have been called (no text: the execute error + // path closes whichever partial tool ask is open) to dismiss the spinner + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith(undefined) + // The write was never approved, so the diff document is reverted before reset + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + }) + + it("runs diff cleanup when handleError rejects", async () => { + // The production handleError awaits Task.say(), which rejects when the task is + // aborted. A rejected handleError must not skip the diff cleanup: the unapproved + // streamed content has to be reverted and the diff view reset, or a user save + // could persist the failed write. The handleError rejection itself propagates + // (it is not swallowed by the cleanup). As in the missing-parameter tests + // above, the revert mock awaits a deferred so the test proves the cleanup + // AWAITs discardUnapprovedStream() before reset(): with the revert still pending, + // reset() must not have run yet. + mockHandleError.mockRejectedValue(new Error("handleError rejected (aborted task)")) + mockedCreateDirectoriesForFile.mockRejectedValue( + Object.assign(new Error("EACCES: permission denied, mkdir '/ro'"), { code: "EACCES" }), + ) + const diffViewCallOrder: string[] = [] + let resolveRevert: () => void = () => {} + const revertDeferred = new Promise((resolve) => { + resolveRevert = resolve + }) + mockCline.diffViewProvider.discardUnapprovedStream.mockImplementation(async () => { + diffViewCallOrder.push("revert") + await revertDeferred + }) + mockCline.diffViewProvider.reset.mockImplementation(async () => { + diffViewCallOrder.push("reset") + }) + + const executePromise = executeWriteFileTool({}, { fileExists: false }) + await new Promise((resolve) => setTimeout(resolve, 0)) + + // handleError was attempted with the write context and the cleanup has reached + // the deferred revert... + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.discardUnapprovedStream).toHaveBeenCalledTimes(1) + // ...and while the revert is still pending, reset() must not have run yet. + expect(mockCline.diffViewProvider.reset).not.toHaveBeenCalled() + + resolveRevert() + await expect(executePromise).rejects.toThrow("handleError rejected (aborted task)") + + // The unapproved content is reverted before the diff view reset. + expect(diffViewCallOrder).toEqual(["revert", "reset"]) + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.saveChanges).not.toHaveBeenCalled() + }) + }) + + describe("prevent focus disruption experiment", () => { + /** + * Enable the PREVENT_FOCUS_DISRUPTION experiment for the current task: the experiment + * branches in execute()/handlePartial() read it from the provider state they fetch. + */ + function enablePreventFocusDisruption(): void { + mockCline.providerRef = { + deref: vi.fn().mockReturnValue({ + getState: vi.fn().mockResolvedValue({ + diagnosticsEnabled: true, + writeDelayMs: 1000, + experiments: { preventFocusDisruption: true }, + }), + }), + } + } + + it("saves through saveDirectly without diff editor interaction when the experiment is enabled", async () => { + enablePreventFocusDisruption() + + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockCline.diffViewProvider.saveDirectly).toHaveBeenCalledWith( + testFilePath, + testContent, + false, + true, + 1000, + // The commit signal: saveDirectly fires it at the filesystem write, which is the only + // place that can say the content landed. + expect.any(Function), + ) + expect(mockCline.diffViewProvider.saveChanges).not.toHaveBeenCalled() + expect(mockCline.ask).not.toHaveBeenCalled() + expect(mockCline.didEditFile).toBe(true) + expect(toolResult).toBe("Tool result message") + }) + + it("keeps approved diff content when saveDirectly fails after approval", async () => { + // The experiment branch stamps writeApproved before saveDirectly, so a late failure + // must NOT revert the document (the user approved the edit and can save it + // manually) but must still finalize the partial ask and reset the diff view. + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + try { + enablePreventFocusDisruption() + mockCline.diffViewProvider.saveDirectly.mockRejectedValue(new Error("save failed")) + + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.finalizePartialToolAsk).toHaveBeenCalledWith(undefined) + expect(mockCline.diffViewProvider.saveDirectly).toHaveBeenCalled() + // discardUnapprovedStream() is what the error path actually calls; asserting only on + // revertChanges() could never fail. + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + expect(mockCline.didEditFile).toBe(false) + } finally { + consoleErrorSpy.mockRestore() + } + }) + + it("does not roll back a write that saveDirectly already landed", async () => { + // The prevent-focus-disruption branch never opens a diff view: saveDirectly() performs + // the write itself, so returning means the content is on disk. A failure in what follows + // (tracking the file, building the result) must not run the rollback over a landed write. + enablePreventFocusDisruption() + mockCline.fileContextTracker.trackFileContext.mockRejectedValueOnce(new Error("tracker down")) + + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockCline.diffViewProvider.saveDirectly).toHaveBeenCalledTimes(1) + expect(mockHandleError).toHaveBeenCalledWith("writing file", expect.any(Error)) + expect(mockCline.diffViewProvider.discardUnapprovedStream).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).toHaveBeenCalled() + }) + + it("skips streaming diff view work when the experiment is enabled", async () => { + // With the experiment enabled the tool preview is embedded in the complete message + // built in execute(), so handlePartial must not open or update the diff view while + // streaming. + enablePreventFocusDisruption() + + // Delta 1 - stabilize path; delta 2 - path stabilized but the experiment short-circuits + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.ask).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.open).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.update).not.toHaveBeenCalled() + }) + + it("releases the per-task stream state when prevent-focus-disruption skips the partial preview", async () => { + // Delta 1 only pins the path, so the entry is still live afterwards (the stream is in + // flight). Delta 2 reaches the experiment check and returns without ever showing a + // preview: nothing else would release the entry or detach the TaskAborted listener. + enablePreventFocusDisruption() + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + expect(writeToFileTool["taskPartialStreamState"].size).toBe(1) + + await executeWriteFileTool({}, { fileExists: false, isPartial: true }) + + expect(mockCline.ask).not.toHaveBeenCalled() + expect(writeToFileTool["taskPartialStreamState"].size).toBe(0) + // Delta 1 registered the listener; delta 2 must detach THAT function, not merely + // some function with the right name. + const abortListener = mockCline.once.mock.calls.find( + ([event]: unknown[]) => event === RooCodeEventName.TaskAborted, + )?.[1] + expect(abortListener).toBeInstanceOf(Function) + expect(mockCline.off).toHaveBeenCalledWith(RooCodeEventName.TaskAborted, abortListener) + }) + + it("clears the provider state when prevent-focus approval is denied", async () => { + // The prevent-focus branch stamps editType/originalContent on the provider before + // asking. On denial nothing was approved and no diff document was opened, so the + // provider state must be cleared (reset) to make a later write re-check the file + // system instead of reusing the stale editType. The non-prevent-focus denial branch + // resets through revertChanges(); this branch must not call it (no document to + // revert). + enablePreventFocusDisruption() + mockAskApproval.mockResolvedValue(false) + + await executeWriteFileTool({}, { fileExists: false }) + + expect(mockAskApproval).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.saveDirectly).not.toHaveBeenCalled() + expect(mockCline.diffViewProvider.reset).toHaveBeenCalledTimes(1) + expect(mockCline.diffViewProvider.revertChanges).not.toHaveBeenCalled() + expect(mockCline.didEditFile).toBe(false) }) }) }) diff --git a/src/core/webview/ClineProvider.ts b/src/core/webview/ClineProvider.ts index 678b93a136..9b9ceb81ec 100644 --- a/src/core/webview/ClineProvider.ts +++ b/src/core/webview/ClineProvider.ts @@ -78,6 +78,7 @@ import { } from "@roo-code/types" import { RateLimitClock, createRateLimitClock } from "../task/RateLimitClock" import { TaskRegistry } from "../task/TaskRegistry" +import { writeToFileTool } from "../tools/WriteToFileTool" import { TaskScheduler } from "../task/TaskScheduler" import { getEffectiveTaskApiConfiguration, @@ -787,6 +788,11 @@ export class ClineProvider removeTaskEventListeners(this.taskEventListeners, task) + // Dispose removes all listeners, so the tool's per-task state must be released + // while the task is still here; otherwise the singleton keeps the disposed task + // and its diff-view provider. + writeToFileTool.clearTaskState(task) + try { await task.dispose() } catch (error) { diff --git a/src/eslint-suppressions.json b/src/eslint-suppressions.json index d5b845997a..33853856a8 100644 --- a/src/eslint-suppressions.json +++ b/src/eslint-suppressions.json @@ -856,7 +856,7 @@ }, "core/tools/__tests__/readFileTool.spec.ts": { "@typescript-eslint/no-explicit-any": { - "count": 96 + "count": 94 } }, "core/tools/__tests__/runSlashCommandTool.spec.ts": { @@ -891,7 +891,7 @@ }, "core/tools/__tests__/writeToFileTool.spec.ts": { "@typescript-eslint/no-explicit-any": { - "count": 5 + "count": 3 } }, "core/tools/helpers/toolResultFormatting.ts": { diff --git a/src/integrations/editor/DiffViewProvider.ts b/src/integrations/editor/DiffViewProvider.ts index 3c1d33ae28..7ac8326ca8 100644 --- a/src/integrations/editor/DiffViewProvider.ts +++ b/src/integrations/editor/DiffViewProvider.ts @@ -21,6 +21,11 @@ import { Task } from "../../core/task/Task" import { DecorationController } from "./DecorationController" +/** Narrow ENOENT test so a rollback can tolerate a file or dir that never landed. */ +function isEnoent(error: unknown): boolean { + return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "ENOENT" +} + export const DIFF_VIEW_URI_SCHEME = "cline-diff" export const DIFF_VIEW_LABEL_CHANGES = "Original ↔ Zoo's Changes" @@ -33,6 +38,14 @@ export class DiffViewProvider { isEditing = false originalContent: string | undefined private createdDirs: string[] = [] + /** + * Absolute path of the empty placeholder open() created for a new-file edit, or undefined + * when no placeholder is outstanding. reset() does NOT clear relPath, and saveDirectly() + * sets relPath for a file that was written with approval, so relPath alone cannot tell a + * caller that a file on disk belongs to the abandoned edit. Only this field justifies an + * unlink. + */ + private placeholderPath: string | undefined private documentWasOpen = false // Tracks whether the target file's tab was pinned before the diff session. // Closing the tab to open the diff drops VS Code's pin state, so we restore @@ -132,6 +145,10 @@ export class DiffViewProvider { // Make sure the file exists before we open it. if (!fileExists) { await fs.writeFile(absolutePath, "") + // From here until the placeholder is removed, THIS edit owns that path. Set after + // the write succeeds, so a failed write does not claim ownership of a file we did + // not create. + this.placeholderPath = absolutePath } // If the file was already open, close it (must happen after showing the @@ -326,6 +343,7 @@ export class DiffViewProvider { async saveChanges( diagnosticsEnabled: boolean = true, writeDelayMs: number = DEFAULT_WRITE_DELAY_MS, + onCommit?: () => void, ): Promise<{ newProblemsMessage: string | undefined userEdits: string | undefined @@ -339,10 +357,27 @@ export class DiffViewProvider { const updatedDocument = this.activeDiffEditor.document const editedContent = updatedDocument.getText() - if (updatedDocument.isDirty) { - await updatedDocument.save() + if (updatedDocument.isDirty && !(await updatedDocument.save())) { + // save() resolving false (without throwing) means the write did not persist. Stop + // BEFORE the commit point: onCommit has not run and placeholderPath stays owned, so + // the caller still holds an uncommitted cleanup state and the teardown removes what + // open() created. Reporting this write as durable would strand an unpersisted file + // whose ownership had already been released. + throw new Error(`Saving ${absolutePath} was not confirmed; the write was not committed.`) } + // The write is irreversible from here: a clean document already matches disk, and a saved + // one has landed. Everything below (closing the diff views, tab bookkeeping, diagnostics) + // can still reject, and a caller that rolls the tool call back after this point would undo + // a write the user approved - so it is told, at the commit point rather than on return. + onCommit?.() + + // Ownership is released only once the approved write has landed. A save that rejects leaves + // the placeholder as open() created it, and the caller's teardown still has to remove it: + // clearing it here would tell discardUnapprovedStream() that nothing this edit created is + // left to clean, and an empty or half-written new file would survive the failed write. + this.placeholderPath = undefined + // Stop tracking touches and cancel any pending scroll-to-diff before any // programmatic editor activation below. this.disposeActiveEditorListener() @@ -513,14 +548,285 @@ export class DiffViewProvider { return JSON.stringify(result) } + /** + * Remove a file this edit created. Tolerates ENOENT: when open() failed before the + * placeholder was written (or the write itself failed) there is nothing to delete, and + * that must not abort the rollback. + */ + private async removeCreatedFile(absolutePath: string): Promise { + try { + await fs.unlink(absolutePath) + } catch (error: unknown) { + if (!isEnoent(error)) { + throw error + } + } + } + + /** Same tolerance for a directory this edit created that never made it to disk. */ + private async removeCreatedDir(dirPath: string): Promise { + try { + await fs.rmdir(dirPath) + } catch (error: unknown) { + if (!isEnoent(error)) { + throw error + } + } + } + + /** + * Whether this edit still owns a placeholder file that cleanup must remove. + * True from the moment open() creates the file until a rollback or commit removes + * it; a failed removal leaves it true so the caller can keep the session (and the + * retry path) instead of resetting the ownership away. + */ + get ownsPlaceholder(): boolean { + return this.placeholderPath !== undefined + } + + /** + * Whether an active edit session belongs to a different path than the one a + * call is about to write. A session is retained when its rollback could not + * complete (a refused save keeps \`isEditing\` and the dirty buffer so the + * user's content survives); a later write for ANOTHER path must not reuse + * that session: it would update and save the old document while requesting + * approval for the new path. + */ + isEditingDifferentPath(relPath: string): boolean { + if (!this.isEditing || this.relPath === undefined) { + return false + } + return this.relPath !== relPath + } + + /** + * The path of the retained edit session, when one is active. Used to tell the + * caller which write must be resolved before another path can be written. + */ + get editingRelPath(): string | undefined { + return this.isEditing ? this.relPath : undefined + } + + /** + * Release the placeholder this edit owns when the approved write never committed: + * saveChanges() threw before its commit point, so the file on disk is still the empty + * placeholder open() created. Leaving it behind unowned would make a later attempt + * treat it as the pre-existing target and strand an empty file no rollback recognizes + * anymore. The dirty editor (it holds the approved content for a manual save or retry) + * and the created directories are deliberately untouched: that save needs both the + * buffer and its parent directories. + */ + async discardOwnedPlaceholder(): Promise { + const placeholderPath = this.placeholderPath + if (!placeholderPath) { + return + } + await this.removeCreatedFile(placeholderPath) + this.placeholderPath = undefined + } + + /** + * Release a diff view whose content was never approved: an abandoned partial stream, + * a failed stream, or a write the user was never asked to approve (rooignore denial, + * validation failure). Deliberately NOT the same as revertChanges(), because + * revertChanges() SAVES and neither abandoned case may write to disk: + * + * - create: its new-file branch saves a dirty buffer as-is before deleting the file, + * which writes partial model output the task never approved - and leaves it on disk + * if the delete then fails. + * - modify: its branch restores the original content and saves it. That is a write to + * a file the user never approved, and for a rooignore-denial path a write the + * policy forbids outright. + * + * Here the target file is never written. A create buffer is emptied FIRST, so the + * only bytes that can ever reach the placeholder are none and the tab is clean enough + * to close without a prompt; a modify buffer is restored to the content already on + * disk in memory only, so the file itself is untouched and the tab (now showing the + * original content, still marked dirty) is left for the user rather than force-closed + * over any edits they may have typed into the preview. The placeholder plus the directories this edit + * created are removed once the buffer outcome is confirmed - a restore applyEdit accepted and, for a + * create, a save it confirmed. While that outcome is unconfirmed the artifacts stay owned and on disk: + * deleting them under a buffer that still holds unapproved content leaves that buffer one save away + * from recreating a file nobody approved. + */ + async discardUnapprovedStream(): Promise { + if (!this.relPath) { + return + } + + const absolutePath = path.resolve(this.cwd, this.relPath) + // Snapshot the directories this edit created BEFORE the editor work below, and clear the field so + // nothing else can act on them twice. The sweep below runs when the buffer outcome is confirmed; + // when it is not, the catch hands this snapshot back, so the retained session's next cleanup still + // knows what this edit put on disk. + const createdDirs = this.createdDirs + this.createdDirs = [] + // Same snapshot for the placeholder, but the ownership stays set until the unlink + // actually succeeds: a failed removal (EPERM) must leave the file owned so the + // caller can keep the session and a retry path instead of stranding it unowned. + const placeholderPath = this.placeholderPath + + let editorFailure: unknown + + // Lifecycle teardown first: ahead of the editor branch below and therefore ahead of the awaited + // buffer restore. open() installs onDidChangeActiveTextEditor, onDidChangeTextEditorSelection + // and onDidChangeTextEditorVisibleRanges, and close() clears activeDiffEditor without + // disposing them, so a discard reached after the view was closed used to sweep the artifacts + // and leave three window-level handlers plus any pending deferred reveal installed on a + // session the caller keeps when this method returns with ownership retained. + this.disposeActiveEditorListener() + this.cancelDeferredScroll() + + // open() creates the directories and the empty placeholder BEFORE it assigns + // activeDiffEditor (openDiffEditor() can reject on its 10s timeout or a failed + // vscode.diff call), so an abandoned create can leave artifacts on disk with no + // editor at all. Only the buffer and tab work needs the editor; the artifact + // cleanup below runs either way. + if (this.activeDiffEditor) { + const document = this.activeDiffEditor.document + // Held until the buffer outcome below confirms itself. A restore applyEdit declined, a save that + // did not confirm, or a rejection anywhere before that confirmation leaves unapproved content in + // a buffer whose tab is still open, and unlinking the file underneath it would let a later save + // of that buffer recreate the file with content nobody ever approved. + let bufferUnconfirmed = true + try { + if (document.isDirty) { + // Restore the buffer to what this edit started from - the empty placeholder for a create, + // the content already on disk for a modify. A refused applyEdit leaves the unapproved streamed + // content in the buffer, and saving then would persist exactly what this method exists to + // discard, so the save is conditional and a refused restore stops the rollback outright below. + const edit = new vscode.WorkspaceEdit() + const fullRange = new vscode.Range( + document.positionAt(0), + document.positionAt(document.getText().length), + ) + const restoredContent = + this.editType === "modify" ? this.stripAllBOMs(this.originalContent ?? "") : "" + edit.replace(document.uri, fullRange, restoredContent) + const applied = await vscode.workspace.applyEdit(edit) + if (!applied) { + // A refused restore leaves the unapproved content in the buffer: closing the tabs and sweeping + // the artifacts underneath it would strand that content with nothing left that can recover it, + // so this stops the rollback outright, exactly as an unconfirmed save of the restored buffer + // does below. The catch restores the createdDirs snapshot and the placeholder stays owned, + // does below. The catch restores the createdDirs snapshot and the placeholder stays owned, + // which is what tells the caller to skip reset() and keep the session for a retry. + throw new Error( + `Could not restore the diff editor buffer for ${this.relPath}; it may still hold unapproved content.`, + ) + } else if (this.editType !== "modify") { + // Only the emptied placeholder is ever saved: this edit created that file, and + // closing a dirty tab would prompt. A modify is never saved here - a modify's + // restore is an in-memory revert, and saving it would write to a file the user + // never approved (see the method comment). A false save leaves the buffer dirty + // over the placeholder: closeAllDiffViews() would skip the dirty tab and the + // unlink would delete the file underneath it, leaving the buffer one save away + // from recreating it - the same hazard revertChanges() refuses, so the rollback + // stops here with the placeholder still owned and the session still retryable. + if (!(await document.save())) { + throw new Error( + `Rollback could not save the restored buffer for ${this.relPath}; its clean state is unconfirmed, so the cleanup stopped before closing tabs or deleting the placeholder.`, + ) + } + } + } + // Close the diff tabs only now: a vscode.diff tab is dirty while its modified side + // holds the streamed content, and closeAllDiffViews() deliberately skips dirty tabs to + // avoid a save prompt. Closing before the restore above left that tab open over a file + // this method is about to unlink. + // Confirmed: the buffer holds nothing this edit streamed - restored, and for a create saved, or + // already clean. A rejection from the closes below can leave a tab open over a clean buffer, a + // lesser hazard than an artifact nothing can remove once the caller resets the session, so + // those rejections still fall through to the sweep. + bufferUnconfirmed = false + await this.closeAllDiffViews() + await this.closeFileTab(absolutePath) + } catch (error) { + // An unconfirmed buffer outcome keeps the placeholder and the created directories exactly as + // they are - owned, on disk - because the retained session is what a retry works from. + if (bufferUnconfirmed) { + // The rollback stopped before the artifact sweep: hand the directory snapshot back with + // the still-owned placeholder, so the next cleanup of this session knows what this edit + // created. The retained ownership is what tells the caller to skip reset(). + this.createdDirs = createdDirs + throw error + } + // Only the tab closes failed, on a buffer whose outcome is confirmed: the placeholder and the + // created directories still have to go, because the caller resets the session afterwards and + // nothing else can remove them. The original failure is re-thrown once they are dealt with. + editorFailure = error + } + } + + let cleanupFailure: unknown + try { + // Only a placeholder THIS edit created may be removed. relPath survives reset(), and + // saveDirectly() sets it for a file that was written with approval, so unlinking + // absolutePath unconditionally can delete content the user approved. + // The field names the path open() created empty; it is not proof that this edit + // still owns the file. Another provider working the same path can write and save + // approved content there while this abandoned session still carries the field, and + // unlinking on the field alone deletes that write. The placeholder open() created is + // zero bytes, so only a file that is still zero bytes is this edit's to remove - the + // ENOENT case and any file with content in it release the ownership and leave the + // bytes alone, which is what a later writer's approved write needs. The helper below + // carries its own ENOENT tolerance for a file that disappears between this stat and + // the unlink, and a failed unlink throws before the field is cleared below, so a + // retained session still owns the placeholder and a retry path still has it recorded. + if (placeholderPath && (await fs.stat(placeholderPath).catch(() => null))?.size === 0) { + await this.removeCreatedFile(placeholderPath) + } + this.placeholderPath = undefined + + // Remove only the directories this edit created, in reverse order. + for (let i = createdDirs.length - 1; i >= 0; i--) { + await this.removeCreatedDir(createdDirs[i]) + } + } catch (error) { + // A sweep that stopped partway leaves whatever it did not reach on disk and untracked, + // because this field was cleared up front. Hand the snapshot back: when the unlink is the + // step that failed the placeholder is still owned, the session is retained, and the next + // discard finishes the sweep in reverse order - the helpers tolerate whatever a partial sweep + // already removed. When only a directory removal failed, ownership is already released and + // the caller-side reset clears this field again, so nothing changes on that path. + this.createdDirs = createdDirs + cleanupFailure = error + console.error("Error removing abandoned write_to_file artifacts:", error) + } + + // Restore any preview tabs the diff evicted, reconstructing the user's prior + // not-yet-edited tab state, the way saveChanges() and revertChanges() do at their own ends. + // The discard path never reached this: reset() clears snapshotPreviewTabs right after, so a + // denied stream left every tab VS Code evicted to open the diff gone for the session. + // Skipped when the sweep failed - the placeholder is then still on disk and still owned, the + // snapshot is the only record the retry path has of what is left to remove, and reopening + // tabs on top of a half-removed artifact would report a workspace that is not restored. + // restorePreviewTabs() reports its own per-tab failures, so it cannot mask editorFailure. + if (!cleanupFailure) { + await this.restorePreviewTabs() + } + if (editorFailure) { + throw editorFailure instanceof Error ? editorFailure : new Error(String(editorFailure)) + } + if (cleanupFailure) { + throw cleanupFailure instanceof Error ? cleanupFailure : new Error(String(cleanupFailure)) + } + } + async revertChanges(): Promise { - if (!this.relPath || !this.activeDiffEditor) { + if (!this.relPath) { return } const fileExists = this.editType === "modify" - const updatedDocument = this.activeDiffEditor.document const absolutePath = path.resolve(this.cwd, this.relPath) + // Only the placeholder THIS edit owns may be deleted. A stale session (a prior reset() + // whose close failed) can carry relPath onto the next call, and the path derived from + // it may name a file this edit never created - e.g. the previously approved write. + // Ownership is released only once the unlink succeeds: a rollback that fails partway + // (refused restore, EPERM unlink) must leave the placeholder OWNED so the caller can + // skip reset() and keep a retry path, instead of stranding the empty file unowned. + // A double unlink from a later discard is safe - removeCreatedFile tolerates ENOENT. // Stop tracking touches and cancel any pending scroll-to-diff before any // programmatic editor activation below. @@ -528,52 +834,101 @@ export class DiffViewProvider { this.cancelDeferredScroll() if (!fileExists) { - if (updatedDocument.isDirty) { - await updatedDocument.save() + // open() creates the parent directories and an empty placeholder file BEFORE it + // awaits openDiffEditor(). If that await rejects there is no activeDiffEditor, and + // the previous early return here left the placeholder and the new directories on + // disk: the next execute() then saw an empty file and treated the requested new file + // as an existing one, so a denial preserved the debris. The filesystem rollback runs + // either way; only the document work needs an editor. + if (this.activeDiffEditor) { + const updatedDocument = this.activeDiffEditor.document + if (updatedDocument.isDirty) { + // The diff tab's modified side holds the streamed content, and the tab is dirty + // while it does: closeAllDiffViews() skips dirty tabs (closing one would prompt), + // so the rollback must put the pre-stream content back and confirm a clean save + // BEFORE any tab or file goes. Unlinking the placeholder underneath an open dirty + // diff tab left the unapproved content one save away from recreating the deleted + // file. A refused restore or an unconfirmed save stops the rollback here - before + // the close and the delete - and propagates as the rollback hazard it is. + const edit = new vscode.WorkspaceEdit() + const fullRange = new vscode.Range( + updatedDocument.positionAt(0), + updatedDocument.positionAt(updatedDocument.getText().length), + ) + edit.replace(updatedDocument.uri, fullRange, this.originalContent ?? "") + if (!(await vscode.workspace.applyEdit(edit))) { + throw new Error( + `Rollback could not restore the buffer for ${absolutePath}; it may still hold unapproved content, so the rollback stopped before closing tabs or deleting the file.`, + ) + } + if (!(await updatedDocument.save())) { + throw new Error( + `Rollback could not save the restored buffer for ${absolutePath}; its clean state is unconfirmed, so the rollback stopped before closing tabs or deleting the file.`, + ) + } + // A file-scheme buffer for the same path, if one is open, holds the same + // unapproved content: discard it with the same restore-save-close discipline. + await this.discardFileTab(absolutePath) + await this.closeAllDiffViews() + } else { + await this.closeAllDiffViews() + // The file was newly created for this edit; close its transiently + // opened tab before deleting it from disk. + await this.closeFileTab(absolutePath) + } } - await this.closeAllDiffViews() - // The file was newly created for this edit; close its transiently - // opened tab before deleting it from disk. - await this.closeFileTab(absolutePath) - await fs.unlink(absolutePath) + if (this.placeholderPath) { + await this.removeCreatedFile(this.placeholderPath) + // The file is gone: release ownership before the directory loop, so a later + // failure there cannot strand an ownership that no longer has a file. + this.placeholderPath = undefined + } // Remove only the directories we created, in reverse order. for (let i = this.createdDirs.length - 1; i >= 0; i--) { - await fs.rmdir(this.createdDirs[i]) + await this.removeCreatedDir(this.createdDirs[i]) } } else { - // Revert document. - const edit = new vscode.WorkspaceEdit() + // The document revert needs the editor. A failed open() (openDiffEditor rejects + // after open() already set relPath/isEditing) leaves none: skip only the document + // work then, and let execution reach the shared teardown below - returning early + // would leave relPath, editType, isEditing and the preview-tab snapshot behind, + // the exact stale-session state this method's rollback guarantees rule out. + const updatedDocument = this.activeDiffEditor?.document + if (updatedDocument) { + // Revert document. + const edit = new vscode.WorkspaceEdit() - const fullRange = new vscode.Range( - updatedDocument.positionAt(0), - updatedDocument.positionAt(updatedDocument.getText().length), - ) + const fullRange = new vscode.Range( + updatedDocument.positionAt(0), + updatedDocument.positionAt(updatedDocument.getText().length), + ) - edit.replace(updatedDocument.uri, fullRange, this.stripAllBOMs(this.originalContent ?? "")) + edit.replace(updatedDocument.uri, fullRange, this.stripAllBOMs(this.originalContent ?? "")) + + // Apply the edit and save, since contents shouldn't have changed + // this won't show in local history unless of course the user made + // changes and saved during the edit. + await vscode.workspace.applyEdit(edit) + await updatedDocument.save() - // Apply the edit and save, since contents shouldn't have changed - // this won't show in local history unless of course the user made - // changes and saved during the edit. - await vscode.workspace.applyEdit(edit) - await updatedDocument.save() + await this.closeAllDiffViews() - await this.closeAllDiffViews() + // Read auto-close preferences from state; fall back to defaults that + // preserve the existing behavior when unset. + const revertTask = this.taskRef.deref() + const revertState = await revertTask?.providerRef.deref()?.getState() - // Read auto-close preferences from state; fall back to defaults that - // preserve the existing behavior when unset. - const revertTask = this.taskRef.deref() - const revertState = await revertTask?.providerRef.deref()?.getState() - - await this.keepOrCloseEditedFile( - absolutePath, - false, - revertState?.autoCloseZooOpenedFiles ?? DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES, - revertState?.autoCloseZooOpenedFilesAfterUserEdited ?? - DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES_AFTER_USER_EDITED, - revertState?.autoCloseZooOpenedNewFiles ?? DEFAULT_AUTO_CLOSE_ZOO_OPENED_NEW_FILES, - ) + await this.keepOrCloseEditedFile( + absolutePath, + false, + revertState?.autoCloseZooOpenedFiles ?? DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES, + revertState?.autoCloseZooOpenedFilesAfterUserEdited ?? + DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES_AFTER_USER_EDITED, + revertState?.autoCloseZooOpenedNewFiles ?? DEFAULT_AUTO_CLOSE_ZOO_OPENED_NEW_FILES, + ) + } } // Restore any preview tabs the diff evicted, reconstructing the user's @@ -847,6 +1202,104 @@ export class DiffViewProvider { // Close the plain (non-diff) editor tab for the target file. Used when the // file was opened transiently for the diff and the user never interacted // with it, so it should not linger after accept/deny. + /** + * Close the tab for this path WITHOUT saving. Used by the new-file rollback, where the + * buffer holds unapproved streamed content that must never reach disk; closeFileTab() + * deliberately skips dirty tabs, so a dirty buffer needs the forced close. + * + * A close that fails or is refused is a rollback failure: the buffer would still hold the + * content the user never approved, one save away from disk. Put the pre-stream content back + * so nothing saveable survives, and propagate - the caller must not keep deleting around a + * buffer it could not discard. + */ + private async discardFileTab(absolutePath: string): Promise { + const tabs = vscode.window.tabGroups.all + .flatMap((group) => group.tabs) + .filter( + (tab) => + tab.input instanceof vscode.TabInputText && + tab.input.uri.scheme === "file" && + arePathsEqual(tab.input.uri.fsPath, absolutePath), + ) + + for (const tab of tabs) { + // tabGroups.close()'s second argument is preserveFocus, not a force-discard flag: a + // dirty tab prompts or is refused, which is how unapproved streamed content survived a + // "forced" close. Restore the buffer to its pre-stream content and save it clean first, + // so close() never sees a dirty tab and nothing unapproved reaches disk. A refused + // restore or an unconfirmed clean save stops the rollback HERE: closing anyway would + // hand the user a save-confirmation prompt over a buffer still holding unapproved + // content (or an unconfirmed state), and answering it yes writes exactly what this + // rollback exists to discard. + if (!(await this.restorePreStreamBuffer(absolutePath))) { + throw new Error( + `Rollback could not restore the buffer for ${absolutePath}; it may still hold unapproved content, so the tab was left open rather than closed.`, + ) + } + if (!(await this.saveBufferClean(absolutePath))) { + throw new Error( + `Rollback could not save the restored buffer for ${absolutePath}; its clean state is unconfirmed, so the tab was left open rather than closed.`, + ) + } + + let closed: boolean + let closeError: Error | undefined + try { + closed = await vscode.window.tabGroups.close(tab) + } catch (error) { + closed = false + closeError = error instanceof Error ? error : new Error(String(error)) + } + if (!closed) { + throw new Error( + `Rollback could not close the restored buffer for ${absolutePath}; its content was put back to the pre-stream state but the tab is still open.`, + { cause: closeError }, + ) + } + } + } + + /** + * Replace an open buffer's content with what it held before streaming started, so a buffer + * that could not be closed never keeps unapproved content available to save. + * + * Returns false when VS Code refuses the edit: the buffer still holds the streamed content, + * and discardFileTab() stops the rollback rather than closing or saving over it. Returns + * true when no open buffer needed restoring or the restore applied. + */ + private async restorePreStreamBuffer(absolutePath: string): Promise { + const document = vscode.workspace.textDocuments.find( + (document) => document.uri.scheme === "file" && arePathsEqual(document.uri.fsPath, absolutePath), + ) + if (!document) { + return true + } + const edit = new vscode.WorkspaceEdit() + const range = new vscode.Range(document.positionAt(0), document.positionAt(document.getText().length)) + edit.replace(document.uri, range, this.originalContent ?? "") + return vscode.workspace.applyEdit(edit) + } + + /** + * Persist a restored buffer so the tab is clean before it is closed: close() refuses or prompts + * on a dirty tab, and a refused close is how unapproved content outlived a "forced" rollback. + * Only reached after discardFileTab()'s restore applied, so what lands here is the pre-stream + * content, never the streamed partial. + * + * Returns false when document.save() does not confirm the save: the buffer may still be dirty, + * so closing would prompt over an unconfirmed state and discardFileTab() stops the rollback + * instead. Returns true when the save completed or there was nothing to save. + */ + private async saveBufferClean(absolutePath: string): Promise { + const document = vscode.workspace.textDocuments.find( + (document) => document.uri.scheme === "file" && arePathsEqual(document.uri.fsPath, absolutePath), + ) + if (!document?.isDirty) { + return true + } + return document.save() + } + private async closeFileTab(absolutePath: string): Promise { const tabs = vscode.window.tabGroups.all .flatMap((group) => group.tabs) @@ -1109,25 +1562,39 @@ export class DiffViewProvider { this.disposeActiveEditorListener() this.cancelDeferredScroll() - await this.closeAllDiffViews() - this.editType = undefined - this.isEditing = false - this.originalContent = undefined - this.createdDirs = [] - this.documentWasOpen = false - this.documentWasPinned = false - this.activeDiffEditor = undefined - this.fadedOverlayController = undefined - this.activeLineController = undefined - this.streamedLines = [] - this.preDiagnostics = [] - this.preEditScrollLine = undefined - this.diffScrollLine = undefined - this.targetFileScrollLine = undefined - this.lastScrolledSource = undefined - this.userTouchedDocument = false - this.userTouchedDiffEditor = false - this.snapshotPreviewTabs = [] + try { + await this.closeAllDiffViews() + } finally { + // Clear the session even when the close rejected: a stale relPath/editType/isEditing + // surviving a failed reset is what turned one bad tab-close into loss of approved + // content - the next execution skips open(), reuses the stale create session, and a + // later denial's rollback deletes the file the previous write approved. The close + // failure still propagates to the caller. + this.editType = undefined + this.isEditing = false + // A session's path must not outlive the session: revertChanges() reads relPath to decide + // what to roll back, and a stale relPath with editType cleared points the next rollback at + // whatever file this provider last touched - a file the current edit never created. + this.relPath = undefined + this.newContent = undefined + this.originalContent = undefined + this.createdDirs = [] + this.placeholderPath = undefined + this.documentWasOpen = false + this.documentWasPinned = false + this.activeDiffEditor = undefined + this.fadedOverlayController = undefined + this.activeLineController = undefined + this.streamedLines = [] + this.preDiagnostics = [] + this.preEditScrollLine = undefined + this.diffScrollLine = undefined + this.targetFileScrollLine = undefined + this.lastScrolledSource = undefined + this.userTouchedDocument = false + this.userTouchedDiffEditor = false + this.snapshotPreviewTabs = [] + } } /** @@ -1137,6 +1604,8 @@ export class DiffViewProvider { * @param relPath - Relative path to the file * @param content - Content to write to the file * @param openFile - Whether to show the file in editor (false = open in memory only for diagnostics) + * @param onCommit - Called at the filesystem write below, the point after which a rollback + * would delete content that already landed * @returns Result of the save operation including any new problems detected */ async saveDirectly( @@ -1145,10 +1614,12 @@ export class DiffViewProvider { openFile: boolean = true, diagnosticsEnabled: boolean = true, writeDelayMs: number = DEFAULT_WRITE_DELAY_MS, + onCommit?: () => void, ): Promise<{ newProblemsMessage: string | undefined userEdits: string | undefined finalContent: string | undefined + openFailure: string | undefined }> { const absolutePath = path.resolve(this.cwd, relPath) @@ -1158,28 +1629,50 @@ export class DiffViewProvider { // Write the content directly to the file await createDirectoriesForFile(absolutePath) await fs.writeFile(absolutePath, content, "utf-8") + // The write is the commit point, the same line saveChanges() signals its commit and releases + // the placeholder at: the document open, the forced save and the diagnostics below can all + // still reject, and a caller that rolled the call back after this point would delete content + // that already landed. + onCommit?.() + // Ownership is released at the same point saveChanges() releases it, and only for the + // placeholder that names this very file: a session retained on another path keeps its own + // placeholder owned, because this write never created it. + if (this.placeholderPath === absolutePath) { + this.placeholderPath = undefined + } + // The write above is the commit point: an opening failure that follows it is not a + // publish failure, so the committed outcome and its bookkeeping are kept and the + // opening failure is reported alongside them instead of replacing them. + let openFailure: string | undefined + const noteOpenFailure = (error: unknown): void => { + openFailure = error instanceof Error ? error.message : String(error) + console.warn(`Opening ${absolutePath} failed after its content was committed: ${openFailure}`) + } // Open the document to ensure diagnostics are loaded // When openFile is false (PREVENT_FOCUS_DISRUPTION enabled), we only open in memory - if (openFile) { - // Show the document in the editor - await vscode.window.showTextDocument(vscode.Uri.file(absolutePath), { - preview: false, - preserveFocus: true, - }) - } else { - // Just open the document in memory to trigger diagnostics without showing it - const doc = await vscode.workspace.openTextDocument(vscode.Uri.file(absolutePath)) + try { + if (openFile) { + // Show the document in the editor + await vscode.window.showTextDocument(vscode.Uri.file(absolutePath), { + preview: false, + preserveFocus: true, + }) + } else { + // Just open the document in memory to trigger diagnostics without showing it + const doc = await vscode.workspace.openTextDocument(vscode.Uri.file(absolutePath)) - // Save the document to ensure VSCode recognizes it as saved and triggers diagnostics - if (doc.isDirty) { - await doc.save() - } + // Save the document to ensure VSCode recognizes it as saved and triggers diagnostics + if (doc.isDirty) { + await doc.save() + } - // Force a small delay to ensure diagnostics are triggered - await new Promise((resolve) => setTimeout(resolve, 100)) + // Force a small delay to ensure diagnostics are triggered + await new Promise((resolve) => setTimeout(resolve, 100)) + } + } catch (error) { + noteOpenFailure(error) } - let newProblemsMessage = "" if (diagnosticsEnabled) { @@ -1222,6 +1715,7 @@ export class DiffViewProvider { newProblemsMessage, userEdits: undefined, finalContent: content, + openFailure, } } } diff --git a/src/integrations/editor/__tests__/DiffViewProvider.spec.ts b/src/integrations/editor/__tests__/DiffViewProvider.spec.ts index e94a66e1db..a5a7d632ec 100644 --- a/src/integrations/editor/__tests__/DiffViewProvider.spec.ts +++ b/src/integrations/editor/__tests__/DiffViewProvider.spec.ts @@ -1,12 +1,26 @@ +import type { Stats } from "fs" +import * as fs from "fs/promises" import { DiffViewProvider, DIFF_VIEW_URI_SCHEME, DIFF_VIEW_LABEL_CHANGES } from "../DiffViewProvider" import { DecorationController } from "../DecorationController" import type { Task } from "../../../core/task/Task" import type { Mock } from "vitest" import * as vscode from "vscode" import delay from "delay" -import { DEFAULT_WRITE_DELAY_MS } from "@roo-code/types" - -import { makePosition, makeRange, makeTextDocument, makeTextEditor, makeUri } from "../../../test-utils/vscode" +import { + DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES, + DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES_AFTER_USER_EDITED, + DEFAULT_AUTO_CLOSE_ZOO_OPENED_NEW_FILES, + DEFAULT_WRITE_DELAY_MS, +} from "@roo-code/types" + +import { + makeDisposable, + makePosition, + makeRange, + makeTextDocument, + makeTextEditor, + makeUri, +} from "../../../test-utils/vscode" // Mock delay vi.mock("delay", () => ({ @@ -18,6 +32,14 @@ vi.mock("fs/promises", () => ({ readFile: vi.fn().mockResolvedValue("file content"), writeFile: vi.fn().mockResolvedValue(undefined), access: vi.fn().mockResolvedValue(undefined), + // revertChanges() rolls a new-file edit back by deleting the placeholder and the + // directories the edit created. + unlink: vi.fn().mockResolvedValue(undefined), + rmdir: vi.fn().mockResolvedValue(undefined), + // The abandoned-stream cleanup stats the placeholder before unlinking it: only the + // file open() created empty is its own to delete. The default double reports exactly + // that zero-byte placeholder; rows that mean a filled file override it once. + stat: vi.fn(async () => ({ size: 0 })), })) // Mock utils @@ -54,7 +76,7 @@ vi.mock("vscode", () => ({ onDidChangeTextEditorVisibleRanges: vi.fn(() => ({ dispose: vi.fn() })), tabGroups: { all: [], - close: vi.fn(), + close: vi.fn().mockResolvedValue(true), activeTabGroup: { activeTab: undefined }, }, visibleTextEditors: [], @@ -840,6 +862,24 @@ describe("DiffViewProvider", () => { expect(mockDelay).toHaveBeenCalledWith(0) }) + it("keeps the committed outcome and reports the opening failure separately when the open rejects after publication", async () => { + const fsMock = await import("fs/promises") + const reason = new Error("TextEditorService refused to show the document") + vi.mocked(vscode.window.showTextDocument).mockRejectedValueOnce(reason) + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}) + + const result = await diffViewProvider.saveDirectly("test.ts", "new content", true, false, 0) + + // The write landed before the open failed, so the committed result is still returned + // and the opening failure travels as its own field rather than as a failed publish. + expect(fsMock.writeFile).toHaveBeenCalledWith(`${mockCwd}/test.ts`, "new content", "utf-8") + expect(result.finalContent).toBe("new content") + expect(result.userEdits).toBeUndefined() + expect(result.openFailure).toContain("TextEditorService refused to show the document") + expect(warn).toHaveBeenCalledWith(expect.stringContaining("failed after its content was committed")) + warn.mockRestore() + }) + it("should store results for formatFileWriteResponse", async () => { await diffViewProvider.saveDirectly("test.ts", "new content", true, true, 1000) @@ -1086,7 +1126,16 @@ describe("DiffViewProvider", () => { describe("userTouchedDocument close/keep behavior", () => { const mockTargetPath = `${mockCwd}/mock-target-file.ts` - const buildActiveDiffEditor = () => + // vscode types `TextDocument.isDirty` as read-only, but the doubles in this block are plain + // objects that a test has to dirty on purpose before `saveChanges()` runs. Widening the + // document view of this one builder keeps every `editor.document.isDirty = ...` below a + // plain assignment: the mutable structural type is what `makeTextDocument` actually hands + // back at runtime, so no assertion and no `any` is needed. + type ActiveDiffEditor = Omit & { + document: Omit & { isDirty: boolean } + } + + const buildActiveDiffEditor = (): ActiveDiffEditor => makeTextEditor({ document: makeTextDocument({ uri: makeUri(mockTargetPath), @@ -1130,6 +1179,794 @@ describe("DiffViewProvider", () => { expect(vscode.window.showTextDocument).toHaveBeenCalled() }) + it("revertChanges() removes the placeholder and created dirs when open() failed before the editor existed", async () => { + // open() creates the parent dirs and an empty placeholder BEFORE it awaits + // openDiffEditor(). If that await rejects there is no activeDiffEditor, and the + // rollback used to bail out - leaving an empty file that the next execute() mistook + // for an existing file, which a denial then preserved. + const createdDirs = [`${mockCwd}/new-parent`, `${mockCwd}/new-parent/nested`] + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs, + // open() claimed the placeholder before its editor open rejected. + placeholderPath: `${mockCwd}/mock-target-file.ts`, + }) + + await diffViewProvider.revertChanges() + + expect(fs.unlink).toHaveBeenCalledWith(`${mockCwd}/mock-target-file.ts`) + expect(fs.rmdir).toHaveBeenNthCalledWith(1, createdDirs[1]) + expect(fs.rmdir).toHaveBeenNthCalledWith(2, createdDirs[0]) + }) + + it("revertChanges() tolerates a placeholder that was never written", async () => { + // The failed open may have died before fs.writeFile ran; ENOENT during the + // rollback is success, not a new failure that would abort the cleanup. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [], + // Ownership was claimed (open()'s write succeeded); the file vanished externally + // before the rollback ran. + placeholderPath: `${mockCwd}/mock-target-file.ts`, + }) + vi.mocked(fs.unlink).mockRejectedValueOnce(Object.assign(new Error("ENOENT"), { code: "ENOENT" })) + + await expect(diffViewProvider.revertChanges()).resolves.toBeUndefined() + + // The rollback still attempted the delete - the tolerance is about not + // aborting the rest of the cleanup, not about skipping it. + expect(fs.unlink).toHaveBeenCalledWith(`${mockCwd}/mock-target-file.ts`) + }) + + it("open() does not claim placeholder ownership when the placeholder write fails", async () => { + // The failed open may have died inside fs.writeFile(); placeholderPath is set only + // after the write succeeds, so a failed write must not mark a file this edit never + // created as owned, and the rollback must still remove the directories it did + // create without unlinking the unowned path. + const { createDirectoriesForFile } = await import("../../../utils/fs") + vi.mocked(createDirectoriesForFile).mockResolvedValueOnce([`${mockCwd}/new-parent`]) + vi.mocked(fs.writeFile).mockRejectedValueOnce(new Error("EACCES: permission denied")) + + await expect(diffViewProvider.open("mock-target-file.ts")).rejects.toThrow("EACCES: permission denied") + + expect(diffViewProvider["placeholderPath"]).toBeUndefined() + expect(diffViewProvider["createdDirs"]).toEqual([`${mockCwd}/new-parent`]) + + await diffViewProvider.revertChanges() + + expect(fs.unlink).not.toHaveBeenCalled() + expect(fs.rmdir).toHaveBeenCalledWith(`${mockCwd}/new-parent`) + }) + + it("discardOwnedPlaceholder() unlinks the owned placeholder and releases ownership", async () => { + // The approved-but-uncommitted state: the file on disk is still the empty + // placeholder this edit created, so removing it is safe and releasing ownership + // after the removal keeps reset() from stranding it unowned. + diffViewProvider["placeholderPath"] = mockTargetPath + + await diffViewProvider.discardOwnedPlaceholder() + + expect(fs.unlink).toHaveBeenCalledWith(mockTargetPath) + expect(diffViewProvider["placeholderPath"]).toBeUndefined() + // The public getter, not only the field it reads: nothing else in this spec asserts the released + // state, so a getter that always reported true would pass the suite. + expect(diffViewProvider.ownsPlaceholder).toBe(false) + }) + + it("discardOwnedPlaceholder() keeps ownership when the removal fails", async () => { + // An EPERM unlink must not release ownership: the placeholder is still on disk, + // and the caller needs the intact state to retry or to report the hazard. + diffViewProvider["placeholderPath"] = mockTargetPath + vi.mocked(fs.unlink).mockRejectedValueOnce( + Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" }), + ) + + await expect(diffViewProvider.discardOwnedPlaceholder()).rejects.toThrow("EPERM: operation not permitted") + expect(diffViewProvider["placeholderPath"]).toBe(mockTargetPath) + }) + + it("discardOwnedPlaceholder() is a no-op without ownership and tolerates a vanished file", async () => { + // An edit that never created a file must not unlink anything, and a placeholder + // that vanished externally is still a released ownership, not a new failure. + await diffViewProvider.discardOwnedPlaceholder() + expect(fs.unlink).not.toHaveBeenCalled() + + diffViewProvider["placeholderPath"] = mockTargetPath + vi.mocked(fs.unlink).mockRejectedValueOnce(Object.assign(new Error("ENOENT"), { code: "ENOENT" })) + + await expect(diffViewProvider.discardOwnedPlaceholder()).resolves.toBeUndefined() + expect(diffViewProvider["placeholderPath"]).toBeUndefined() + }) + + it("revertChanges() stops before the document work for an existing file when no editor exists", async () => { + // The modify branch used to dereference activeDiffEditor unconditionally. When open() + // never produced an editor there is no document to restore, and the old code threw a + // TypeError out of the denial path instead of finishing the teardown. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "modify", + createdDirs: [], + }) + + await expect(diffViewProvider.revertChanges()).resolves.toBeUndefined() + + expect(vscode.workspace.applyEdit).not.toHaveBeenCalled() + expect(fs.unlink).not.toHaveBeenCalled() + expect(fs.rmdir).not.toHaveBeenCalled() + // Only the document work is skipped: the shared teardown still runs, so no + // stale session survives the rollback. + expect(diffViewProvider["relPath"]).toBeUndefined() + expect(diffViewProvider["isEditing"]).toBe(false) + expect(diffViewProvider["editType"]).toBeUndefined() + }) + + it("revertChanges() keeps rolling back the remaining directories when one rmdir hits ENOENT", async () => { + // Same tolerance as the placeholder, for the created dirs: a directory that never + // landed must not abort the rest of the rollback and must not surface as a new failure. + const createdDirs = [`${mockCwd}/new-parent`, `${mockCwd}/new-parent/nested`] + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs, + }) + vi.mocked(fs.rmdir).mockRejectedValueOnce(Object.assign(new Error("ENOENT"), { code: "ENOENT" })) + + await expect(diffViewProvider.revertChanges()).resolves.toBeUndefined() + + expect(fs.rmdir).toHaveBeenCalledTimes(2) + expect(fs.rmdir).toHaveBeenNthCalledWith(1, createdDirs[1]) + expect(fs.rmdir).toHaveBeenNthCalledWith(2, createdDirs[0]) + }) + + it("revertChanges() surfaces a non-ENOENT directory failure instead of swallowing it", async () => { + // The tolerance is scoped to ENOENT: a directory that exists but could not be removed + // is a real rollback failure and must reach the caller rather than be hidden. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [`${mockCwd}/new-parent`], + }) + vi.mocked(fs.rmdir).mockRejectedValueOnce(Object.assign(new Error("EBUSY"), { code: "EBUSY" })) + + await expect(diffViewProvider.revertChanges()).rejects.toThrow("EBUSY") + }) + + it("revertChanges() keeps placeholder ownership when the unlink fails", async () => { + // A rollback that cannot remove the placeholder must leave it OWNED: the caller + // skips reset() on that signal and keeps a retry path, instead of the empty file + // being stranded unowned for the next attempt to mistake for an existing file. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [], + placeholderPath: mockTargetPath, + }) + vi.mocked(fs.unlink).mockRejectedValueOnce( + Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" }), + ) + + await expect(diffViewProvider.revertChanges()).rejects.toThrow("EPERM: operation not permitted") + expect(diffViewProvider["placeholderPath"]).toBe(mockTargetPath) + expect(diffViewProvider.ownsPlaceholder).toBe(true) + }) + + it("revertChanges() releases placeholder ownership once the unlink succeeded even if a directory removal fails", async () => { + // Ownership tracks the file, not the whole rollback: after the unlink lands, the + // ownership is released before the directory loop, so a later EBUSY cannot strand + // an ownership whose file no longer exists. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [`${mockCwd}/new-parent`], + placeholderPath: mockTargetPath, + }) + vi.mocked(fs.rmdir).mockRejectedValueOnce(Object.assign(new Error("EBUSY"), { code: "EBUSY" })) + + await expect(diffViewProvider.revertChanges()).rejects.toThrow("EBUSY") + expect(fs.unlink).toHaveBeenCalledWith(mockTargetPath) + expect(diffViewProvider["placeholderPath"]).toBeUndefined() + }) + + it("discardUnapprovedStream() keeps placeholder ownership when the unlink fails", async () => { + // Same discipline as revertChanges(): the abandoned-stream cleanup runs even with + // no editor, and a failed unlink must leave the placeholder owned so the caller + // can skip reset() and keep a retry path instead of stranding it unowned. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [], + placeholderPath: mockTargetPath, + }) + vi.mocked(fs.unlink).mockRejectedValueOnce( + Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" }), + ) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("EPERM: operation not permitted") + expect(diffViewProvider["placeholderPath"]).toBe(mockTargetPath) + }) + + it("revertChanges() after reset() does not unlink a file this edit never created", async () => { + // reset() used to leave relPath behind with editType cleared, which is exactly the state + // that sends the NEXT rollback down the new-file branch: fs.unlink on whatever file this + // provider last touched. A truncated tool call or an EACCES in a later write then deleted + // a file the user had already saved. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [], + placeholderPath: mockTargetPath, + }) + + await diffViewProvider.reset() + await diffViewProvider.revertChanges() + + expect(diffViewProvider["relPath"]).toBeUndefined() + expect(fs.unlink).not.toHaveBeenCalled() + }) + it("revertChanges() after a FAILED reset does not delete the previously approved file", async () => { + // An approved new-file write landed and reset() then rejected on the tab close. + // Without the finally, relPath/editType/isEditing and the placeholder ownership + // survived the failure: the next execution skipped open(), reused the stale create + // session, and a later denial's rollback unlinked the file the user had approved. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + isEditing: true, + createdDirs: [], + placeholderPath: mockTargetPath, + }) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockRejectedValue(new Error("close failed")) + + await expect(diffViewProvider.reset()).rejects.toThrow("close failed") + + // The failed reset still released the session and the placeholder ownership. + expect(diffViewProvider["relPath"]).toBeUndefined() + expect(diffViewProvider["editType"]).toBeUndefined() + expect(diffViewProvider["isEditing"]).toBe(false) + expect(diffViewProvider["placeholderPath"]).toBeUndefined() + + // The next edit's denial rolls back owning no placeholder: the previously approved + // file must survive even though a relPath is set again. The tab close succeeds this + // time - only the rollback's delete authority is under test. + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + Object.assign(diffViewProvider, { + relPath: "follow-up-denied.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [], + }) + await diffViewProvider.revertChanges() + expect(fs.unlink).not.toHaveBeenCalled() + }) + + it("saveChanges() signals its commit point at the document save, not on return", async () => { + // Everything after the save - closing the diff views, tab bookkeeping, diagnostics - can + // still reject. A caller that rolls the tool call back on that rejection would undo a + // write that already landed, so it has to be told at the save rather than when the + // method returns. + const order: string[] = [] + const editor = buildActiveDiffEditor() + editor.document.isDirty = true + editor.document.save = vi.fn(async () => { + order.push("save") + return true + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + newContent: "content", + activeDiffEditor: editor, + placeholderPath: mockTargetPath, + closeFileTab: vi.fn().mockResolvedValue(undefined), + restorePreviewTabs: vi.fn().mockResolvedValue(undefined), + }) + diffViewProvider["closeAllDiffViews"] = vi.fn(async () => { + order.push("closeDiffViews") + }) + + await diffViewProvider.saveChanges(false, 0, () => { + order.push("commit") + }) + + expect(order).toEqual(["save", "commit", "closeDiffViews"]) + // Ownership follows the same line: the placeholder open() created is only released once + // the approved content is on disk. + expect(diffViewProvider["placeholderPath"]).toBeUndefined() + }) + + it("saveChanges() withholds the commit point and the placeholder when the save rejects", async () => { + // A rejected save means nothing landed. Signalling the commit point anyway would tell + // the caller the rollback has to stand down, and clearing placeholderPath would tell + // discardUnapprovedStream() that nothing this edit created is left to remove - the empty + // or half-written new file would survive the failed write. + const order: string[] = [] + const editor = buildActiveDiffEditor() + editor.document.isDirty = true + editor.document.save = vi.fn(async () => { + order.push("save") + throw new Error("save rejected") + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + newContent: "content", + activeDiffEditor: editor, + placeholderPath: mockTargetPath, + closeFileTab: vi.fn().mockResolvedValue(undefined), + }) + + await expect(diffViewProvider.saveChanges(false, 0, () => order.push("commit"))).rejects.toThrow( + "save rejected", + ) + + expect(order).toEqual(["save"]) + expect(diffViewProvider["placeholderPath"]).toBe(mockTargetPath) + }) + + it("saveChanges() does not commit when the save resolves false", async () => { + // save() can resolve false without throwing: the write did not persist. The commit + // point was never reached, so onCommit must not run and the placeholder must stay + // owned - reporting the write as durable would strand an unpersisted file whose + // cleanup ownership had already been released. + const order: string[] = [] + const editor = buildActiveDiffEditor() + editor.document.isDirty = true + editor.document.save = vi.fn(async () => { + order.push("save") + return false + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + newContent: "content", + activeDiffEditor: editor, + placeholderPath: mockTargetPath, + }) + + await expect(diffViewProvider.saveChanges(false, 0, () => order.push("commit"))).rejects.toThrow( + "was not confirmed; the write was not committed", + ) + + expect(order).toEqual(["save"]) + expect(diffViewProvider["placeholderPath"]).toBe(mockTargetPath) + }) + + it("saveChanges() commits an already-clean document and releases placeholder ownership", async () => { + // A clean document already matches disk and never saves, but it crosses the same + // commit point: the callback must run and the placeholder ownership must be + // released even though no save happened. + const editor = buildActiveDiffEditor() + editor.document.isDirty = false + const onCommit = vi.fn() + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["closeFileTab"] = vi.fn().mockResolvedValue(undefined) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + newContent: "content", + activeDiffEditor: editor, + placeholderPath: mockTargetPath, + documentWasOpen: false, + userTouchedDocument: false, + preEditScrollLine: undefined, + editType: "modify", + originalContent: "original", + }) + + await diffViewProvider.saveChanges(false, 0, onCommit) + + expect(editor.document.save).not.toHaveBeenCalled() + expect(onCommit).toHaveBeenCalledTimes(1) + expect(diffViewProvider["placeholderPath"]).toBeUndefined() + }) + + it("revertChanges() surfaces a placeholder delete that failed for a non-ENOENT reason", async () => { + // The ENOENT tolerance is scoped: an unlink that fails for another reason means the + // unapproved placeholder is still on disk, and the caller must not be told the + // rollback succeeded. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [], + placeholderPath: mockTargetPath, + }) + vi.mocked(fs.unlink).mockRejectedValueOnce( + Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }), + ) + + await expect(diffViewProvider.revertChanges()).rejects.toThrow("EACCES: permission denied") + }) + + it("revertChanges() restores the streamed buffer to its pre-stream content before closing and unlinking a new file", async () => { + // The diff buffer holds the streamed content of a write that was never approved. + // Saving it as-is persisted exactly what this rollback is undoing - local history, file + // watchers, and, if the delete below fails, the content itself. The rollback restores the + // pre-stream content first and only then saves, so the only content ever written is the + // empty pre-stream buffer. + const editor = buildActiveDiffEditor() + editor.document.isDirty = true + editor.document.save = vi.fn().mockResolvedValue(true) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + const dirtyTab = { + input: Object.assign(new vscode.TabInputText(makeUri(mockTargetPath)), { + uri: makeUri(mockTargetPath), + }), + isDirty: true, + label: "mock-target-file.ts", + } + const originalTabs = Object.getOwnPropertyDescriptor(vscode.window.tabGroups, "all") + Object.defineProperty(vscode.window.tabGroups, "all", { + get: () => [{ tabs: [dirtyTab] }], + configurable: true, + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: editor, + editType: "create", + createdDirs: [], + originalContent: "", + placeholderPath: mockTargetPath, + }) + + try { + await diffViewProvider.revertChanges() + } finally { + // Do not leak the tab fixture: later tests read the module-level tabGroups.all. + if (originalTabs) { + Object.defineProperty(vscode.window.tabGroups, "all", originalTabs) + } + } + + expect(editor.document.save).toHaveBeenCalledTimes(1) + const [, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedText).toBe("") + // No force argument: tabGroups.close()'s second parameter is preserveFocus, not a + // discard flag, so passing true never discarded anything - it only suppressed the + // prompt while the dirty tab was silently refused. + expect(vscode.window.tabGroups.close).toHaveBeenCalledWith(dirtyTab) + expect(fs.unlink).toHaveBeenCalledWith(mockTargetPath) + }) + + it("revertChanges() cleans and closes the dirty vscode.diff tab before unlinking the new file", async () => { + // The denial-path hazard named on the pre-merge check: openDiffEditor() opens a + // vscode.diff tab whose input is a TabInputTextDiff, closeAllDiffViews() skips that tab + // while its modified side is dirty, and unlinking the placeholder underneath the open + // dirty tab left unapproved content one save away from recreating the deleted file. + // The provider's own tab helpers are deliberately NOT stubbed: the tab cleanup order + // through the real helpers is what is under test. + const callOrder: string[] = [] + const document = { + isDirty: true, + getText: () => "partial model output", + positionAt: (offset: number) => ({ line: 0, character: offset }), + uri: makeUri(mockTargetPath), + save: vi.fn(async () => { + callOrder.push("save") + document.isDirty = false + return true + }), + } + const diffTab = { + label: `mock-target-file.ts ${DIFF_VIEW_LABEL_CHANGES}`, + input: Object.assign(new vscode.TabInputTextDiff(makeUri("diff-original"), makeUri(mockTargetPath)), { + original: { scheme: DIFF_VIEW_URI_SCHEME, fsPath: "mock-target-file.ts" }, + modified: { scheme: "file", fsPath: mockTargetPath }, + }), + // The tab is dirty exactly while the modified-side buffer is: the rollback has to + // make the buffer clean for the tab to become closeable at all. + get isDirty() { + return document.isDirty + }, + } + const originalTabs = Object.getOwnPropertyDescriptor(vscode.window.tabGroups, "all") + Object.defineProperty(vscode.window.tabGroups, "all", { + get: () => [{ tabs: [diffTab] }], + configurable: true, + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: { document }, + editType: "create", + createdDirs: [], + originalContent: "", + placeholderPath: mockTargetPath, + }) + vi.mocked(vscode.workspace.applyEdit).mockImplementation(async () => { + callOrder.push("applyEdit") + return true + }) + vi.mocked(vscode.window.tabGroups.close).mockImplementation(async () => { + callOrder.push("closeTab") + return true + }) + vi.mocked(fs.unlink).mockImplementation(async () => { + callOrder.push("unlink") + return undefined + }) + + try { + await diffViewProvider.revertChanges() + } finally { + // Do not leak the tab fixture: later tests read the module-level tabGroups.all. + if (originalTabs) { + Object.defineProperty(vscode.window.tabGroups, "all", originalTabs) + } + } + + // The buffer is put back to its pre-stream (empty) content and saved clean before + // anything closes, and the tab is gone before the file is deleted: no save can + // recreate the abandoned file from a buffer the user never approved. + expect(callOrder.slice(0, 2)).toEqual(["applyEdit", "save"]) + const [, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedText).toBe("") + expect(callOrder.indexOf("closeTab")).toBeGreaterThan(-1) + expect(callOrder.indexOf("closeTab")).toBeLessThan(callOrder.indexOf("unlink")) + expect(fs.unlink).toHaveBeenCalledWith(mockTargetPath) + }) + + it("revertChanges() reports a discard the editor refused instead of leaving the buffer open", async () => { + // A forced close can still fail (a vetoing editor). Swallowing that left the unapproved + // streamed content in an open, saveable buffer while the rollback kept deleting the + // file underneath it. The failure must propagate, and the buffer must be put back to + // its pre-stream state so nothing saveable survives. + const editor = buildActiveDiffEditor() + editor.document.isDirty = true + // The diff-side restore/save confirms; the file-scheme buffer below is the one + // whose close gets vetoed. + editor.document.save = vi.fn().mockResolvedValue(true) + const streamedBuffer = { + uri: makeUri(mockTargetPath), + getText: vi.fn().mockReturnValue("streamed content"), + isDirty: true, + positionAt: vi.fn().mockReturnValue({ line: 0, character: 0 }), + save: vi.fn().mockResolvedValue(true), + } + const dirtyTab = { + input: Object.assign(new vscode.TabInputText(makeUri(mockTargetPath)), { + uri: makeUri(mockTargetPath), + }), + isDirty: true, + label: "mock-target-file.ts", + } + const originalTabs = Object.getOwnPropertyDescriptor(vscode.window.tabGroups, "all") + const originalDocuments = Object.getOwnPropertyDescriptor(vscode.workspace, "textDocuments") + Object.defineProperty(vscode.window.tabGroups, "all", { + get: () => [{ tabs: [dirtyTab] }], + configurable: true, + }) + Object.defineProperty(vscode.workspace, "textDocuments", { + value: [streamedBuffer], + configurable: true, + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: editor, + editType: "create", + createdDirs: [], + originalContent: "", + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + vi.mocked(vscode.window.tabGroups.close).mockRejectedValueOnce(new Error("close vetoed")) + + try { + await expect(diffViewProvider.revertChanges()).rejects.toThrow("could not close the restored buffer") + } finally { + if (originalTabs) { + Object.defineProperty(vscode.window.tabGroups, "all", originalTabs) + } + if (originalDocuments) { + Object.defineProperty(vscode.workspace, "textDocuments", originalDocuments) + } + } + + // The buffer went back to its pre-stream state and was saved clean BEFORE the close, + // so the close never saw a dirty tab; the rollback then stopped rather than deleting the + // file out from under a buffer it could not discard. + expect(vscode.workspace.applyEdit).toHaveBeenCalled() + expect(streamedBuffer.save).toHaveBeenCalledTimes(1) + expect(vscode.window.tabGroups.close).toHaveBeenCalledWith(dirtyTab) + // The buffer was put back to its pre-stream state (empty for a new file): the edit that + // was applied replaces the streamed text with originalContent. + const appliedEdit = vi.mocked(vscode.WorkspaceEdit).mock.results[0].value + expect(appliedEdit.replace).toHaveBeenCalledWith( + expect.objectContaining({ fsPath: mockTargetPath }), + expect.anything(), + "", + ) + }) + + it("revertChanges() stops the rollback without closing when the buffer restore is refused", async () => { + // applyEdit resolving false leaves the streamed content in the buffer. Saving it would + // persist exactly what this rollback exists to discard, and closing the dirty tab would + // trade the rollback report for a save-confirmation prompt over unapproved content, so + // the rollback stops and reports instead. + const editor = buildActiveDiffEditor() + editor.document.isDirty = true + const streamedBuffer = { + uri: makeUri(mockTargetPath), + getText: vi.fn().mockReturnValue("streamed content"), + isDirty: true, + positionAt: vi.fn().mockReturnValue({ line: 0, character: 0 }), + save: vi.fn().mockResolvedValue(undefined), + } + const dirtyTab = { + input: Object.assign(new vscode.TabInputText(makeUri(mockTargetPath)), { + uri: makeUri(mockTargetPath), + }), + isDirty: true, + label: "mock-target-file.ts", + } + const originalTabs = Object.getOwnPropertyDescriptor(vscode.window.tabGroups, "all") + const originalDocuments = Object.getOwnPropertyDescriptor(vscode.workspace, "textDocuments") + Object.defineProperty(vscode.window.tabGroups, "all", { + get: () => [{ tabs: [dirtyTab] }], + configurable: true, + }) + Object.defineProperty(vscode.workspace, "textDocuments", { + value: [streamedBuffer], + configurable: true, + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: editor, + editType: "create", + createdDirs: [], + originalContent: "", + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValueOnce(false) + + try { + await expect(diffViewProvider.revertChanges()).rejects.toThrow(/could not restore the buffer/i) + } finally { + if (originalTabs) { + Object.defineProperty(vscode.window.tabGroups, "all", originalTabs) + } + if (originalDocuments) { + Object.defineProperty(vscode.workspace, "textDocuments", originalDocuments) + } + } + + // The restore was attempted and refused; the save that would have written the unapproved + // streamed content to disk never ran, and the dirty tab was NOT closed - closing it + // would trade a safe rollback report for a save-confirmation prompt over unapproved + // content. The rollback stops here and reports. + expect(vscode.workspace.applyEdit).toHaveBeenCalled() + expect(streamedBuffer.save).not.toHaveBeenCalled() + expect(vscode.window.tabGroups.close).not.toHaveBeenCalled() + }) + + it("revertChanges() stops the rollback when the file buffer restore is the refused one", async () => { + // The row above refuses the first applyEdit, which is the diff-editor restore, so the + // file-scheme buffer's own restore - the guard in front of the tab close - is never the + // one under test. Here the diff-side restore and its save both confirm, so the rollback + // reaches the file-scheme buffer and THAT restore is the refusal: the class has to stop + // before closing a tab whose buffer still holds the streamed content. + const editor = buildActiveDiffEditor() + editor.document.isDirty = true + editor.document.save = vi.fn().mockResolvedValue(true) + const streamedBuffer = { + uri: makeUri(mockTargetPath), + getText: vi.fn().mockReturnValue("streamed content"), + isDirty: true, + positionAt: vi.fn((offset: number) => ({ line: 0, character: offset })), + save: vi.fn().mockResolvedValue(true), + } + const fileTab = { + input: Object.assign(new vscode.TabInputText(makeUri(mockTargetPath)), { + uri: makeUri(mockTargetPath), + }), + isDirty: true, + label: "mock-target-file.ts", + } + const originalTabs = Object.getOwnPropertyDescriptor(vscode.window.tabGroups, "all") + const originalDocuments = Object.getOwnPropertyDescriptor(vscode.workspace, "textDocuments") + Object.defineProperty(vscode.window.tabGroups, "all", { + get: () => [{ tabs: [fileTab] }], + configurable: true, + }) + Object.defineProperty(vscode.workspace, "textDocuments", { + value: [streamedBuffer], + configurable: true, + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: editor, + editType: "create", + createdDirs: [], + originalContent: "", + }) + // The first applyEdit is the diff-editor restore and it lands; the second is the + // file-scheme buffer's restore, and that is the one VS Code refuses. + vi.mocked(vscode.workspace.applyEdit).mockResolvedValueOnce(true).mockResolvedValueOnce(false) + + try { + await expect(diffViewProvider.revertChanges()).rejects.toThrow(/could not restore the buffer/i) + } finally { + if (originalTabs) { + Object.defineProperty(vscode.window.tabGroups, "all", originalTabs) + } + if (originalDocuments) { + Object.defineProperty(vscode.workspace, "textDocuments", originalDocuments) + } + } + + // Both restores were attempted, so the refusal that stopped the rollback is the second one; + // the diff-side save confirmed and the file-scheme buffer was neither saved nor closed. + expect(vscode.workspace.applyEdit).toHaveBeenCalledTimes(2) + expect(editor.document.save).toHaveBeenCalledTimes(1) + expect(streamedBuffer.save).not.toHaveBeenCalled() + expect(vscode.window.tabGroups.close).not.toHaveBeenCalled() + }) + + it("revertChanges() stops the rollback without closing when the clean save is not confirmed", async () => { + // document.save() resolving false leaves the buffer's clean state unconfirmed. Closing + // then would prompt the user over a possibly-dirty tab, and answering yes can write + // content the rollback never confirmed clean, so the close is skipped and the failure + // is reported. + const editor = buildActiveDiffEditor() + editor.document.isDirty = true + // The diff-side restore/save confirms; the file-scheme buffer below is the one whose + // save stays unconfirmed. + editor.document.save = vi.fn().mockResolvedValue(true) + const streamedBuffer = { + uri: makeUri(mockTargetPath), + getText: vi.fn().mockReturnValue("streamed content"), + isDirty: true, + positionAt: vi.fn().mockReturnValue({ line: 0, character: 0 }), + save: vi.fn().mockResolvedValue(false), + } + const dirtyTab = { + input: Object.assign(new vscode.TabInputText(makeUri(mockTargetPath)), { + uri: makeUri(mockTargetPath), + }), + isDirty: true, + label: "mock-target-file.ts", + } + const originalTabs = Object.getOwnPropertyDescriptor(vscode.window.tabGroups, "all") + const originalDocuments = Object.getOwnPropertyDescriptor(vscode.workspace, "textDocuments") + Object.defineProperty(vscode.window.tabGroups, "all", { + get: () => [{ tabs: [dirtyTab] }], + configurable: true, + }) + Object.defineProperty(vscode.workspace, "textDocuments", { + value: [streamedBuffer], + configurable: true, + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: editor, + editType: "create", + createdDirs: [], + originalContent: "", + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + + try { + await expect(diffViewProvider.revertChanges()).rejects.toThrow(/could not save the restored buffer/i) + } finally { + if (originalTabs) { + Object.defineProperty(vscode.window.tabGroups, "all", originalTabs) + } + if (originalDocuments) { + Object.defineProperty(vscode.workspace, "textDocuments", originalDocuments) + } + } + + // The restore applied and the save was attempted, but the unconfirmed save stops the + // rollback before the close. + expect(streamedBuffer.save).toHaveBeenCalledTimes(1) + expect(vscode.window.tabGroups.close).not.toHaveBeenCalled() + }) + it("revertChanges() closes the file tab when the file was not open and untouched", async () => { const closeFileTab = vi.fn().mockResolvedValue(undefined) vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) @@ -1776,4 +2613,1275 @@ describe("DiffViewProvider", () => { expect(vscode.window.showTextDocument).toHaveBeenCalled() }) }) + describe("discardUnapprovedStream method", () => { + const mockTargetPath = `${mockCwd}/mock-target-file.ts` + + const makeAbandonedDocument = (callOrder: string[], isDirty = true) => ({ + isDirty, + getText: () => "partial model output", + positionAt: (offset: number) => ({ line: 0, character: offset }), + uri: { fsPath: mockTargetPath, path: mockTargetPath }, + save: vi.fn(async () => { + callOrder.push("save") + // A confirmed save: the discard treats an unconfirmed one as a rollback failure. + return true + }), + }) + + const openAbandonedView = (document: unknown, createdDirs: string[], callOrder: string[]) => + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: { document }, + editType: "create", + createdDirs, + // open() records the placeholder it wrote; the discard may only delete what it owns. + placeholderPath: `${mockCwd}/mock-target-file.ts`, + closeAllDiffViews: vi.fn(async () => { + callOrder.push("closeDiffViews") + }), + closeFileTab: vi.fn(async () => { + callOrder.push("closeFileTab") + }), + }) + + it("never persists the unapproved buffer: blanks it with an empty replacement, then deletes the placeholder", async () => { + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + openAbandonedView(document, [], callOrder) + vi.mocked(vscode.workspace.applyEdit).mockImplementation(async () => { + callOrder.push("applyEdit") + return true + }) + + await diffViewProvider.discardUnapprovedStream() + + expect(callOrder).toEqual(["applyEdit", "save", "closeDiffViews", "closeFileTab"]) + // The only content the discard may write is an empty buffer, and it must be + // written to THIS document before the save that would otherwise persist the + // partial model output. + expect(mockWorkspaceEdit.replace).toHaveBeenCalledTimes(1) + const [replacedUri, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedUri).toEqual(document.uri) + // The replacement covers the whole buffer: the range is built from + // positionAt(0) to positionAt(getText().length), so nothing can survive it. + expect(vi.mocked(vscode.Range)).toHaveBeenCalledWith( + { line: 0, character: 0 }, + { line: 0, character: "partial model output".length }, + ) + expect(replacedText).toBe("") + expect(mockWorkspaceEdit.delete).not.toHaveBeenCalled() + // The placeholder for THIS relPath is what gets removed. + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("mock-target-file.ts")) + }) + + it("releases the placeholder instead of unlinking a path another writer filled", async () => { + // The field only names the path open() created empty - it does not prove this edit still + // owns the file. A second provider working the same path can write and save approved + // content into that file while this abandoned session still carries the field, and the + // unlink the cleanup used to run unconditionally deletes that approved write. The bytes + // are somebody else's now, so only the ownership is released here. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + openAbandonedView(document, [], callOrder) + // 42 bytes on disk: not the empty placeholder this edit created. + vi.mocked(fs.stat).mockResolvedValueOnce({ size: 42 } as unknown as Stats) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValueOnce(true) + + await diffViewProvider.discardUnapprovedStream() + + // The buffer work still happened (the restore is mocked to resolve, so it is not + // recorded in the order list): + expect(callOrder).toEqual(["save", "closeDiffViews", "closeFileTab"]) + // ...but the file with content in it is not unlinked, and the ownership is released so + // the caller can reset the session without a later cleanup deleting the write again. + expect(fs.unlink).not.toHaveBeenCalled() + expect(diffViewProvider["placeholderPath"]).toBeUndefined() + expect(diffViewProvider["ownsPlaceholder"]).toBe(false) + }) + + it("restores a modify buffer in memory and never saves the target file", async () => { + // revertChanges() restores a modify by applyEdit + document.save(). For a stream the + // user never approved that save is a write they never asked for, and for a + // .rooignore-denied path a write the policy forbids outright, so the discard restores + // the buffer and leaves the file on disk untouched. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + openAbandonedView(document, [], callOrder) + Object.assign(diffViewProvider, { + editType: "modify", + originalContent: "original content", + // A modify owns no placeholder: only open() of a create writes one. + placeholderPath: undefined, + }) + vi.mocked(vscode.workspace.applyEdit).mockImplementation(async () => { + callOrder.push("applyEdit") + return true + }) + + await diffViewProvider.discardUnapprovedStream() + + expect(callOrder).toEqual(["applyEdit", "closeDiffViews", "closeFileTab"]) + const [replacedUri, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedUri).toEqual(document.uri) + expect(replacedText).toBe("original content") + // The replacement covers the whole buffer, so no streamed content survives it. + expect(vi.mocked(vscode.Range)).toHaveBeenCalledWith( + { line: 0, character: 0 }, + { line: 0, character: "partial model output".length }, + ) + expect(document.save).not.toHaveBeenCalled() + // Nothing is unlinked for a modify: saveChanges() may have written this very file with + // the user's approval, and this edit created no directories. + expect(fs.unlink).not.toHaveBeenCalled() + expect(fs.rmdir).not.toHaveBeenCalled() + }) + + it("stops the cleanup and keeps the placeholder when the buffer restore is refused", async () => { + // applyEdit resolving false leaves the unapproved partial content in the buffer. Saving then + // would persist exactly what this method exists to discard, and closing the tabs or unlinking + // the placeholder underneath that buffer would leave content the user never approved with + // nothing left that can still recover it - so the rollback stops before the close and the + // delete, the same way an unconfirmed save of the restored buffer does. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + openAbandonedView(document, [`${mockCwd}/new-dir`], callOrder) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(false) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow( + /could not restore the diff editor buffer/i, + ) + + expect(document.save).not.toHaveBeenCalled() + // Nothing after the refused restore ran: no close and no unlink. + expect(callOrder).toEqual([]) + expect(fs.unlink).not.toHaveBeenCalled() + expect(fs.rmdir).not.toHaveBeenCalled() + // Ownership and the directory snapshot survive the refused restore. The caller skips reset() + // while the placeholder is still owned, so the retry keeps a session and a discard that still + // knows what it may delete. + expect(diffViewProvider["placeholderPath"] as string | undefined).toBe(mockTargetPath) + expect(diffViewProvider["createdDirs"]).toEqual([`${mockCwd}/new-dir`]) + }) + + it("stops the cleanup and keeps placeholder ownership when the save is not confirmed", async () => { + // document.save() resolving false leaves the emptied buffer dirty over the + // placeholder: closeAllDiffViews() would skip the dirty tab and the unlink would + // delete the file underneath it, leaving the buffer one save away from recreating + // the file from a denied write. The discard stops before the close and the delete, + // keeping ownership so the caller skips reset() and the session stays retryable. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + document.save = vi.fn(async () => { + callOrder.push("save") + return false + }) + const closeAllDiffViews = vi.fn(async () => { + callOrder.push("closeDiffViews") + }) + const closeFileTab = vi.fn(async () => { + callOrder.push("closeFileTab") + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: { document }, + editType: "create", + createdDirs: [`${mockCwd}/new-dir`], + placeholderPath: `${mockCwd}/mock-target-file.ts`, + closeAllDiffViews, + closeFileTab, + }) + vi.mocked(vscode.workspace.applyEdit).mockImplementation(async () => { + callOrder.push("applyEdit") + return true + }) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow( + /could not save the restored buffer/i, + ) + + // The restore was attempted and the save refused; nothing closes and nothing deletes. + expect(callOrder).toEqual(["applyEdit", "save"]) + expect(closeAllDiffViews).not.toHaveBeenCalled() + expect(closeFileTab).not.toHaveBeenCalled() + expect(fs.unlink).not.toHaveBeenCalled() + expect(fs.rmdir).not.toHaveBeenCalled() + // Ownership is preserved: the placeholder is still on disk and still ours. + expect(diffViewProvider["placeholderPath"] as string | undefined).toBe(`${mockCwd}/mock-target-file.ts`) + }) + + it("removes the directories this edit created in reverse order, after the placeholder unlink", async () => { + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + const createdDirs = [`${mockCwd}/mock-dir`, `${mockCwd}/mock-dir/nested`] + openAbandonedView(document, createdDirs, callOrder) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + + await diffViewProvider.discardUnapprovedStream() + + expect(fs.unlink).toHaveBeenCalledTimes(1) + expect(fs.rmdir).toHaveBeenCalledTimes(createdDirs.length) + // Reverse order, so a parent is never removed before the child inside it, and + // only the directories this edit created - never a pre-existing one. + expect(vi.mocked(fs.rmdir).mock.calls.map((c) => c[0])).toEqual([...createdDirs].reverse()) + const unlinkOrder = vi.mocked(fs.unlink).mock.invocationCallOrder[0] + for (const order of vi.mocked(fs.rmdir).mock.invocationCallOrder) { + expect(order).toBeGreaterThan(unlinkOrder) + } + }) + + it("does not save when the abandoned buffer is already clean", async () => { + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder, false) + openAbandonedView(document, [], callOrder) + + await diffViewProvider.discardUnapprovedStream() + + expect(vscode.workspace.applyEdit).not.toHaveBeenCalled() + expect(document.save).not.toHaveBeenCalled() + expect(mockWorkspaceEdit.replace).not.toHaveBeenCalled() + expect(fs.unlink).toHaveBeenCalledTimes(1) + }) + + it("keeps the placeholder and the directories when the buffer restore rejects", async () => { + // A rejected applyEdit leaves the restore unconfirmed, exactly like one that resolves false: the + // buffer still holds the unapproved content and its tab is still open, so unlinking the placeholder + // underneath it would leave that buffer one save away from recreating the file with content nobody + // approved. The artifacts stay owned and the directory snapshot goes back to the session, which is + // what tells the caller to skip reset() and keep the retry path open. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + const createdDirs = [`${mockCwd}/mock-dir`] + openAbandonedView(document, createdDirs, callOrder) + vi.mocked(vscode.workspace.applyEdit).mockRejectedValue(new Error("applyEdit rejected")) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("applyEdit rejected") + + expect(callOrder).toEqual([]) + expect(fs.unlink).not.toHaveBeenCalled() + expect(fs.rmdir).not.toHaveBeenCalled() + expect(diffViewProvider["placeholderPath"] as string | undefined).toBe(mockTargetPath) + expect(diffViewProvider["createdDirs"]).toEqual(createdDirs) + }) + + it("keeps the placeholder and the directories when the restored buffer save rejects", async () => { + // A rejected save is as unconfirmed as one resolving false: the buffer is still dirty over the + // placeholder this edit created, so the sweep must not delete the file underneath it. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + const createdDirs = [`${mockCwd}/mock-dir`] + openAbandonedView(document, createdDirs, callOrder) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + document.save.mockRejectedValueOnce(new Error("save rejected")) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("save rejected") + + // The mock rejects without running its recording body, so the call is counted, not ordered. + expect(document.save).toHaveBeenCalledTimes(1) + expect(callOrder).toEqual([]) + expect(fs.unlink).not.toHaveBeenCalled() + expect(fs.rmdir).not.toHaveBeenCalled() + expect(diffViewProvider["placeholderPath"] as string | undefined).toBe(mockTargetPath) + expect(diffViewProvider["createdDirs"]).toEqual(createdDirs) + }) + + it("sweeps the artifacts when only the tab closes reject on a confirmed buffer", async () => { + // The half of the contract the two tests above must not swallow: once the buffer outcome is + // confirmed, a close failure still has to leave the artifacts gone, because the caller resets the + // session after a throw and nothing else can remove them. The failure still surfaces. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + openAbandonedView(document, [`${mockCwd}/mock-dir`], callOrder) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + Object.assign(diffViewProvider, { + closeAllDiffViews: vi.fn().mockRejectedValue(new Error("close rejected")), + }) + vi.mocked(fs.unlink).mockResolvedValue(undefined) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("close rejected") + + expect(fs.unlink).toHaveBeenCalledWith(mockTargetPath) + expect(fs.rmdir).toHaveBeenCalledWith(`${mockCwd}/mock-dir`) + expect(diffViewProvider["placeholderPath"] as string | undefined).toBeUndefined() + }) + + it("disposes the touch listeners and cancels the deferred scroll while the buffer restore is still pending", async () => { + // Review row wM62emT0. The window a late deferred reveal can fire in is exactly the window the + // buffer restore is awaited in, so this test holds applyEdit() open, starts the discard, and + // asks whether the teardown already happened before the restoration is settled. Fake timers keep + // that window open instead of leaning on wall-clock scheduling, and the restoration is resolved in + // a finally block so the pending promise cannot outlive the test. The handle is declared out + // of the try on purpose: a failure inside the try must report itself instead of being replaced + // by the reference error a finally-block read of an uninitialised let would raise. + let settleRestore: (applied: boolean) => void = () => {} + vi.useFakeTimers() + try { + const callOrder: string[] = [] + const revealRange = vi.fn() + const document = makeTextDocument({ + uri: makeUri(mockTargetPath), + getText: vi.fn().mockReturnValue("a\nCHANGED\nc\nd\n"), + positionAt: vi.fn((offset: number) => makePosition(0, offset)), + }) + Object.assign(document, { isDirty: true }) + const editor = makeTextEditor({ document, visibleRanges: [makeRange()], revealRange }) + const disposeActive = vi.fn() + const disposeSelection = vi.fn() + const disposeScroll = vi.fn() + openAbandonedView(document, [], callOrder) + Object.assign(diffViewProvider, { + activeDiffEditor: editor, + editType: "modify", + originalContent: "a\nb\nc\nd\n", + placeholderPath: undefined, + diffScrollLine: 1, + activeEditorListener: makeDisposable({ dispose: disposeActive }), + diffEditorSelectionListener: makeDisposable({ dispose: disposeSelection }), + diffScrollListener: makeDisposable({ dispose: disposeScroll }), + }) + vi.mocked(vscode.window).visibleTextEditors = [editor] + // The keep path re-shows the edited file; give that re-show an editor double so the + // assertions below are the only thing this test can fail on. + vi.mocked(vscode.window.showTextDocument).mockResolvedValue(makeTextEditor()) + // Schedule the deferred re-reveal the way a tool does, then deny the stream while it is + // still pending. The first reveal is the immediate one; only a surviving timer would add a + // second one after the buffer was already restored. + diffViewProvider.scrollToFirstDiff() + expect(revealRange).toHaveBeenCalledTimes(1) + vi.mocked(vscode.workspace.applyEdit).mockImplementation( + () => + new Promise((resolve) => { + settleRestore = resolve + }), + ) + const discarding = diffViewProvider.discardUnapprovedStream() + await Promise.resolve() + await Promise.resolve() + expect(disposeActive).toHaveBeenCalledOnce() + expect(disposeSelection).toHaveBeenCalledOnce() + expect(disposeScroll).toHaveBeenCalledOnce() + expect(diffViewProvider["deferredScrollTimer"]).toBeUndefined() + // Advancing past the deferred reveal must not put the viewport anywhere: the timer was + // cancelled before the restore was awaited, so there is no late reveal left to fire. + vi.advanceTimersByTime(2000) + expect(revealRange).toHaveBeenCalledTimes(1) + settleRestore(true) + await discarding + expect(callOrder).toEqual(["closeDiffViews", "closeFileTab"]) + } finally { + settleRestore(true) + vi.useRealTimers() + } + }) + + it("disposes the touch listeners on the path where the abandoned view is already closed", async () => { + // Review row wM62emT0, the half the sweep-only test below does not cover. open() installs + // onDidChangeActiveTextEditor, onDidChangeTextEditorSelection and + // onDidChangeTextEditorVisibleRanges, and close() clears activeDiffEditor without touching + // them. A discard reached from that state used to run the sweep and nothing else: the three + // window-level handlers and any pending deferred reveal stayed installed on a session the + // caller may keep for a retry, and reset() is not called when ownership is retained. + vi.useFakeTimers() + try { + const disposeActive = vi.fn() + const disposeSelection = vi.fn() + const disposeScroll = vi.fn() + const lateReveal = vi.fn() + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [], + placeholderPath: mockTargetPath, + activeEditorListener: makeDisposable({ dispose: disposeActive }), + diffEditorSelectionListener: makeDisposable({ dispose: disposeSelection }), + diffScrollListener: makeDisposable({ dispose: disposeScroll }), + // The pending reveal is seeded here, next to the listeners, because the field is declared + // ReturnType on the provider while this file resolves the global timer call + // to the other declaration; assigning the same handle through bracket notation would need an + // assertion. Same handle, same fake clock, same late-reveal guard. + deferredScrollTimer: setTimeout(lateReveal, 300), + }) + vi.mocked(fs.unlink).mockResolvedValue(undefined) + await diffViewProvider.discardUnapprovedStream() + expect(disposeActive).toHaveBeenCalledOnce() + expect(disposeSelection).toHaveBeenCalledOnce() + expect(disposeScroll).toHaveBeenCalledOnce() + expect(diffViewProvider["deferredScrollTimer"]).toBeUndefined() + vi.advanceTimersByTime(1000) + expect(lateReveal).not.toHaveBeenCalled() + expect(fs.unlink).toHaveBeenCalledWith(mockTargetPath) + } finally { + vi.useRealTimers() + } + }) + it("reopens a preview tab the diff evicted before reset() drops the snapshot", async () => { + // Review row wM62emT7. restorePreviewTabs() is defined at DiffViewProvider.ts:1135 and + // called from saveChanges() and revertChanges(), but the discard path never reached it, so a + // denied stream left every preview tab VS Code evicted to open the diff gone: reset() clears + // snapshotPreviewTabs and nothing reopens what it held. + const revealRange = vi.fn() + vi.mocked(vscode.window.showTextDocument).mockResolvedValue(makeTextEditor({ revealRange })) + // No tab in any group: the captured file is one the diff evicted. + Object.defineProperty(vscode.window.tabGroups, "all", { + get: (): vscode.TabGroup[] => [], + configurable: true, + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "modify", + createdDirs: [], + placeholderPath: undefined, + snapshotPreviewTabs: [ + { + uri: makeSnapshotUri(`${mockCwd}/mock-preview-tab.ts`), + scrollLine: 7, + viewColumn: vscode.ViewColumn.One, + }, + ], + }) + await diffViewProvider.discardUnapprovedStream() + await diffViewProvider.reset() + expect(vscode.window.showTextDocument).toHaveBeenCalledWith( + { fsPath: `${mockCwd}/mock-preview-tab.ts`, scheme: "file" }, + { preview: true, preserveFocus: true, viewColumn: vscode.ViewColumn.One }, + ) + expect(revealRange).toHaveBeenCalledTimes(1) + expect(revealRange).toHaveBeenCalledWith( + expect.objectContaining({ start: { line: 7, character: 0 } }), + vscode.TextEditorRevealType.AtTop, + ) + expect(diffViewProvider["snapshotPreviewTabs"]).toEqual([]) + }) + + it("leaves the snapshot in place when the artifact sweep fails so the retry can finish it", async () => { + // The restoration is skipped, not merely ordered late, when the sweep failed: the placeholder + // is still on disk and owned, and reopening the evicted tabs would report a restored + // workspace on top of a half-removed artifact while the snapshot is the only record the + // retry path has of what is left to remove. + Object.defineProperty(vscode.window.tabGroups, "all", { + get: (): vscode.TabGroup[] => [], + configurable: true, + }) + vi.mocked(vscode.window.showTextDocument).mockResolvedValue(makeTextEditor()) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [], + placeholderPath: mockTargetPath, + snapshotPreviewTabs: [ + { + uri: makeSnapshotUri(`${mockCwd}/mock-preview-tab.ts`), + scrollLine: 7, + viewColumn: vscode.ViewColumn.One, + }, + ], + }) + vi.mocked(fs.unlink).mockRejectedValueOnce(new Error("EPERM: operation not permitted")) + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("EPERM") + expect(vscode.window.showTextDocument).not.toHaveBeenCalled() + expect(diffViewProvider["snapshotPreviewTabs"]).toHaveLength(1) + }) + it("removes the placeholder and created directories even when open() failed before activeDiffEditor was assigned", async () => { + // open() creates the directories (line 130) and the empty placeholder (line 134) + // BEFORE openDiffEditor() assigns activeDiffEditor (line 173). If that call rejects + // - the 10s timeout or a failed vscode.diff - an abandoned create therefore has + // artifacts on disk and no editor, and the early return must not skip the cleanup. + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: undefined, + editType: "create", + createdDirs: [`${mockCwd}/mock-dir`], + // open() had already written the placeholder before openDiffEditor() rejected, + // so this edit owns the path. + placeholderPath: `${mockCwd}/mock-target-file.ts`, + }) + + await diffViewProvider.discardUnapprovedStream() + + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("mock-target-file.ts")) + expect(fs.rmdir).toHaveBeenCalledWith(`${mockCwd}/mock-dir`) + // Nothing editor-side ran, and nothing threw: the artifacts are the whole job here. + expect(vscode.workspace.applyEdit).not.toHaveBeenCalled() + // Bracket access for the private field: the snapshot must be consumed, so a second + // discard cannot try to remove the same directories again. + expect(diffViewProvider["createdDirs"]).toEqual([]) + }) + + it("logs and rejects when the placeholder unlink fails for a reason other than ENOENT", async () => { + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + openAbandonedView(document, [], callOrder) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + const permissionError = Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" }) + vi.mocked(fs.unlink).mockRejectedValueOnce(permissionError) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("EPERM: operation not permitted") + + expect(errorSpy).toHaveBeenCalledWith("Error removing abandoned write_to_file artifacts:", permissionError) + }) + + it("hands the created directories back when the unlink fails, so the retained session can finish the sweep", async () => { + // The unlink is the first step of the sweep, so an EPERM there leaves the placeholder owned - + // which is what keeps the session - and the directories this edit created still on disk. + // If the snapshot is not handed back the retained session forgets them and the retry can + // only remove the file. Two directories, so the retry has to show the reverse order again. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + const dirA = `${mockCwd}/mock-dir-a` + const dirB = `${mockCwd}/nested/mock-dir-b` + openAbandonedView(document, [dirA, dirB], callOrder) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + vi.mocked(fs.unlink).mockRejectedValueOnce( + Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" }), + ) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("EPERM: operation not permitted") + + // Owned, on disk and still tracked: that trio is what makes a retry able to finish the job. + expect(diffViewProvider["placeholderPath"] as string | undefined).toBe(mockTargetPath) + expect(diffViewProvider["createdDirs"]).toEqual([dirA, dirB]) + expect(fs.rmdir).not.toHaveBeenCalled() + + await diffViewProvider.discardUnapprovedStream() + + expect(fs.unlink).toHaveBeenCalledTimes(2) + expect(diffViewProvider["placeholderPath"] as string | undefined).toBeUndefined() + expect(diffViewProvider["createdDirs"]).toEqual([]) + expect(vi.mocked(fs.rmdir).mock.calls.map((c) => c[0])).toEqual([dirB, dirA]) + expect(errorSpy).toHaveBeenCalledTimes(1) + errorSpy.mockRestore() + }) + + it("logs and rejects when removing a created directory fails for a reason other than ENOENT", async () => { + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + openAbandonedView(document, [`${mockCwd}/mock-dir`], callOrder) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + vi.mocked(fs.unlink).mockResolvedValue(undefined) + const notEmpty = Object.assign(new Error("ENOTEMPTY: directory not empty"), { code: "ENOTEMPTY" }) + vi.mocked(fs.rmdir).mockRejectedValueOnce(notEmpty) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("ENOTEMPTY: directory not empty") + + expect(errorSpy).toHaveBeenCalledWith("Error removing abandoned write_to_file artifacts:", notEmpty) + }) + + it("tolerates an already-deleted placeholder and directories (ENOENT) without throwing", async () => { + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + // Two created directories: the tolerance has to hold for every one of them, so the + // rejection is keyed on the path rather than on which call comes first. + const dirA = `${mockCwd}/mock-dir-a` + const dirB = `${mockCwd}/nested/mock-dir-b` + openAbandonedView(document, [dirA, dirB], callOrder) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + const enoent = Object.assign(new Error("ENOENT"), { code: "ENOENT" }) + // A single unlink call in this flow, so the placeholder stays Once-based. + vi.mocked(fs.unlink).mockRejectedValueOnce(enoent) + vi.mocked(fs.rmdir).mockImplementation(async (dir) => { + if (dir === dirA || dir === dirB) { + throw enoent + } + }) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await expect(diffViewProvider.discardUnapprovedStream()).resolves.toBeUndefined() + + // Both directories were attempted; the assertion is on the paths, not the order. + expect(fs.rmdir).toHaveBeenCalledWith(dirA) + expect(fs.rmdir).toHaveBeenCalledWith(dirB) + expect(errorSpy).not.toHaveBeenCalledWith( + "Error removing abandoned write_to_file artifacts:", + expect.anything(), + ) + + // beforeEach only clears call data, not implementations, so put the default back. + vi.mocked(fs.rmdir).mockResolvedValue(undefined) + }) + + it("reports the editor failure rather than the cleanup failure when both happen", async () => { + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + openAbandonedView(document, [`${mockCwd}/mock-dir`], callOrder) + // The buffer outcome has to be confirmed for the sweep to run at all, which is what makes both + // failures possible in the same call: applyEdit accepted the restore, a tab close then rejects and + // the placeholder unlink that follows it rejects too. + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + Object.assign(diffViewProvider, { + closeAllDiffViews: vi.fn().mockRejectedValue(new Error("close rejected")), + }) + vi.mocked(fs.unlink).mockRejectedValueOnce(Object.assign(new Error("EPERM"), { code: "EPERM" })) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + // The caller reports a rollback hazard from the thrown error, so the ORIGINAL failure is what must + // surface; the cleanup failure is still logged for the operator. + await expect(diffViewProvider.discardUnapprovedStream()).rejects.toThrow("close rejected") + expect(errorSpy).toHaveBeenCalledWith( + "Error removing abandoned write_to_file artifacts:", + expect.objectContaining({ code: "EPERM" }), + ) + }) + + it("leaves a file this edit never created a placeholder for on disk", async () => { + // reset() does not clear relPath, and saveDirectly() sets it for an approved write. + // Without ownership tracking the discard would unlink that approved file: an approved + // write_to_file to A, then a new write_to_file whose block exits through a rollback + // path before open() ever ran, still sees relPath === A. + const callOrder: string[] = [] + const document = makeAbandonedDocument(callOrder) + Object.assign(diffViewProvider, { + relPath: "previously-approved-file.ts", + activeDiffEditor: { document }, + editType: undefined, + createdDirs: [], + placeholderPath: undefined, + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + + await expect(diffViewProvider.discardUnapprovedStream()).resolves.toBeUndefined() + + expect(fs.unlink).not.toHaveBeenCalled() + expect(fs.rmdir).not.toHaveBeenCalled() + // The buffer is still blanked and the tab closed: the unapproved content is gone + // without touching a file the user approved. + expect(mockWorkspaceEdit.replace).toHaveBeenCalledTimes(1) + expect(mockWorkspaceEdit.replace.mock.calls[0][2]).toBe("") + }) + + it("removes the placeholder that a new-file open() wrote, driven through the public methods", async () => { + // The ownership lifecycle lives at the public-method layer, so exercise it there: + // open() writes the empty placeholder and records it, and the discard of an abandoned + // create removes exactly that path. + const relPath = "owned-placeholder.ts" + const fsPath = `${mockCwd}/${relPath}` + const mockEditor = { + document: { + uri: { fsPath, scheme: "file" }, + getText: vi.fn().mockReturnValue(""), + isDirty: false, + save: vi.fn().mockResolvedValue(undefined), + lineCount: 0, + }, + selection: { active: { line: 0, character: 0 }, anchor: { line: 0, character: 0 } }, + edit: vi.fn().mockResolvedValue(true), + revealRange: vi.fn(), + } + // Structural double for the mocked editor: the mock only implements the members + // open() touches, so it is routed through unknown rather than any. + const editor = mockEditor as unknown as vscode.TextEditor + vi.mocked(vscode.window).visibleTextEditors = [editor] + vi.mocked(vscode.window.showTextDocument).mockResolvedValue(editor) + vi.mocked(vscode.workspace.onDidOpenTextDocument).mockImplementation((callback) => { + setTimeout(() => callback({ uri: { fsPath, scheme: "file" } } as vscode.TextDocument), 0) + return { dispose: vi.fn() } + }) + vi.mocked(vscode.window.onDidChangeVisibleTextEditors).mockReturnValue({ dispose: vi.fn() }) + vi.mocked(vscode.window.onDidChangeTextEditorVisibleRanges).mockReturnValue({ dispose: vi.fn() }) + vi.mocked(vscode.languages.getDiagnostics).mockReturnValue([]) + diffViewProvider.editType = "create" + + await diffViewProvider.open(relPath) + + // open() created the placeholder, and this edit now owns it. + expect(fs.writeFile).toHaveBeenCalledWith(fsPath, "") + + await diffViewProvider.discardUnapprovedStream() + + expect(fs.unlink).toHaveBeenCalledWith(fsPath) + }) + + it("does not remove the file once saveChanges() has approved the content", async () => { + // saveChanges() turns the placeholder into approved content and drops this edit's + // claim on it, so a later abandoned cleanup must leave the approved file on disk. + const relPath = "approved-by-save.ts" + const fsPath = `${mockCwd}/${relPath}` + Object.assign(diffViewProvider, { + relPath, + newContent: "approved content", + editType: "create", + createdDirs: [], + placeholderPath: fsPath, + preDiagnostics: [], + activeDiffEditor: { + document: { + uri: { fsPath, scheme: "file" }, + getText: vi.fn().mockReturnValue("approved content"), + isDirty: false, + save: vi.fn().mockResolvedValue(undefined), + }, + }, + closeAllDiffViews: vi.fn().mockResolvedValue(undefined), + closeFileTab: vi.fn().mockResolvedValue(undefined), + }) + vi.mocked(vscode.languages.getDiagnostics).mockReturnValue([]) + vi.mocked(vscode.window.showTextDocument).mockResolvedValue(undefined as never) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + + await diffViewProvider.saveChanges(false, 0) + + await diffViewProvider.discardUnapprovedStream() + + expect(fs.unlink).not.toHaveBeenCalled() + }) + + it("closes the dirty vscode.diff tab that only TabInputTextDiff matches, before the unlink", async () => { + // The hazard named on #1932: openDiffEditor() opens a vscode.diff tab whose input is a + // TabInputTextDiff, so a rollback helper that looks for TabInputText tabs finds nothing, + // closeAllDiffViews() then skips the tab while it is dirty, and the streamed content + // survives in a buffer one save away from recreating a file the user never approved. + // The provider's own tab helpers are deliberately NOT stubbed here: the tab-input matching + // is what is under test. + const callOrder: string[] = [] + const document = { + isDirty: true, + getText: () => "partial model output", + positionAt: (offset: number) => ({ line: 0, character: offset }), + uri: makeUri(mockTargetPath), + save: vi.fn(async () => { + callOrder.push("save") + document.isDirty = false + return true + }), + } + const diffTab = { + label: `mock-target-file.ts ${DIFF_VIEW_LABEL_CHANGES}`, + input: Object.assign(new vscode.TabInputTextDiff(makeUri("diff-original"), makeUri(mockTargetPath)), { + original: { scheme: DIFF_VIEW_URI_SCHEME, fsPath: "mock-target-file.ts" }, + modified: { scheme: "file", fsPath: mockTargetPath }, + }), + // The tab is dirty exactly while the modified-side buffer is: the discard has to make + // the buffer clean for the tab to become closeable at all. + get isDirty() { + return document.isDirty + }, + } + const originalTabs = Object.getOwnPropertyDescriptor(vscode.window.tabGroups, "all") + Object.defineProperty(vscode.window.tabGroups, "all", { + get: () => [{ tabs: [diffTab] }], + configurable: true, + }) + Object.assign(diffViewProvider, { + relPath: "mock-target-file.ts", + activeDiffEditor: { document }, + editType: "create", + createdDirs: [], + placeholderPath: mockTargetPath, + }) + vi.mocked(vscode.workspace.applyEdit).mockImplementation(async () => { + callOrder.push("applyEdit") + return true + }) + vi.mocked(vscode.window.tabGroups.close).mockImplementation(async () => { + callOrder.push("closeTab") + return true + }) + vi.mocked(fs.unlink).mockImplementation(async () => { + callOrder.push("unlink") + return undefined + }) + + try { + await diffViewProvider.discardUnapprovedStream() + } finally { + // Do not leak the tab fixture: later tests read the module-level tabGroups.all. + if (originalTabs) { + Object.defineProperty(vscode.window.tabGroups, "all", originalTabs) + } + } + + // The buffer is emptied before anything is closed, and the only content the discard + // writes is an empty buffer: a later save has nothing left to persist. + expect(callOrder.slice(0, 2)).toEqual(["applyEdit", "save"]) + const [, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedText).toBe("") + // The tab is gone before the file is, so no save can recreate the abandoned file from a + // buffer the user never approved. + expect(callOrder.indexOf("closeTab")).toBeGreaterThan(-1) + expect(callOrder.indexOf("closeTab")).toBeLessThan(callOrder.indexOf("unlink")) + expect(fs.unlink).toHaveBeenCalledWith(mockTargetPath) + }) + + it("does nothing when no abandoned view is open", async () => { + Object.assign(diffViewProvider, { relPath: undefined, activeDiffEditor: undefined }) + + await diffViewProvider.discardUnapprovedStream() + + expect(fs.unlink).not.toHaveBeenCalled() + }) + }) + describe("isEditingDifferentPath and editingRelPath", () => { + // The production predicate the streaming guard and the different-path rejection both call. + // Everywhere else a test double stands in for it, so only these assertions can fail when the + // predicate itself regresses - for example to always reporting "not a different path". + it("reports no different path while no edit session is active", () => { + Object.assign(diffViewProvider, { isEditing: false, relPath: "leftover/path.ts" }) + + expect(diffViewProvider.isEditingDifferentPath("any/path.ts")).toBe(false) + expect(diffViewProvider.editingRelPath).toBeUndefined() + }) + + it("accepts the retained path and rejects another one", () => { + Object.assign(diffViewProvider, { isEditing: true, relPath: "retained/path.ts" }) + + expect(diffViewProvider.isEditingDifferentPath("retained/path.ts")).toBe(false) + expect(diffViewProvider.isEditingDifferentPath("other/path.ts")).toBe(true) + expect(diffViewProvider.editingRelPath).toBe("retained/path.ts") + }) + + it("compares the paths exactly as the caller spelled them", () => { + // Deliberately no normalisation: the predicate is a plain inequality, so a caller that hands + // over a differently spelled form of the retained path is treated as a second write. Pinning + // it here is what stops a later normalisation from silently widening the guard with nobody + // deciding that. + Object.assign(diffViewProvider, { isEditing: true, relPath: "dir/path.ts" }) + + expect(diffViewProvider.isEditingDifferentPath("./dir/path.ts")).toBe(true) + expect(diffViewProvider.isEditingDifferentPath("dir/path.ts")).toBe(false) + }) + }) + + describe("blocking rows this unit owns at head d52c1614f6e4", () => { + // Each it below closes a line of the 50 blocking rows the mutation-diff leg published at + // p1066/u6-execute-error-path-cleanup d52c1614f6e4. The lines named here are the ones this + // unit's own diff defines: for each of them no earlier-merging unit in the chain + // (U3 #1931, U4 #1929, U5a #1930, U5b #2435) adds the same line against its own merge base, + // so the construct is this unit's to settle and no suppression directive is used anywhere. + const settleRelPath = "settled-target-file.ts" + const settleTargetPath = `${mockCwd}/settled-target-file.ts` + + // revertChanges() reads only uri/getText/positionAt/isDirty/save off the diff document, + // so the double stays that narrow and every input the rollback decides on is an argument. + const makeRollbackDocument = (content: string, isDirty: boolean, saved: boolean) => ({ + uri: makeUri(settleTargetPath), + getText: vi.fn().mockReturnValue(content), + // Distinct answers per offset: a fixture that returned (0,0) for every offset could not tell a + // full-buffer range from an empty one. The Range double wraps whatever positions it is given. + positionAt: vi.fn((offset: number) => + offset === 0 ? { line: 0, character: 0 } : { line: 1, character: offset }, + ), + isDirty, + save: vi.fn().mockResolvedValue(saved), + }) + + const makeDirtyFileTab = () => ({ + input: Object.assign(new vscode.TabInputText(makeUri(settleTargetPath)), { + uri: makeUri(settleTargetPath), + }), + isDirty: true, + label: settleRelPath, + }) + + // Both fixtures below sit on module-level VS Code properties the provider reads live, so each + // run installs its own value and hands the original descriptor back rather than leaking state. + const withTabGroupsAll = (tabs: unknown[], run: () => Promise) => { + const original = Object.getOwnPropertyDescriptor(vscode.window.tabGroups, "all") + Object.defineProperty(vscode.window.tabGroups, "all", { get: () => [{ tabs }], configurable: true }) + return run().finally(() => { + if (original) { + Object.defineProperty(vscode.window.tabGroups, "all", original) + } + }) + } + + const withTextDocuments = (documents: unknown[], run: () => Promise) => { + const original = Object.getOwnPropertyDescriptor(vscode.workspace, "textDocuments") + Object.defineProperty(vscode.workspace, "textDocuments", { value: documents, configurable: true }) + return run().finally(() => { + if (original) { + Object.defineProperty(vscode.workspace, "textDocuments", original) + } + }) + } + + it("line 596: reports no different path when the session flag is up but its retained path is gone", () => { + // The guard's other exit. isEditing can stay true with relPath already cleared by a reset + // whose tab close rejected, and falling through to the comparison would then call every + // later write a second write, because undefined differs from every path. + Object.assign(diffViewProvider, { isEditing: true, relPath: undefined }) + + expect(diffViewProvider.isEditingDifferentPath("any/path.ts")).toBe(false) + }) + + it("line 833: restores the recorded content rather than an empty buffer when a new-file rollback meets a dirty diff buffer", async () => { + const document = makeRollbackDocument("partial model output", true, true) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "create", + createdDirs: [], + placeholderPath: undefined, + originalContent: "the content the file held before this write", + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + + await withTabGroupsAll([makeDirtyFileTab()], () => diffViewProvider.revertChanges()) + + // Distinct positions prove the range spans the buffer: an empty or reversed range would hand + // the Range double the same position twice, and the uri is the document being rolled back. + const [replacedUri, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedUri).toBe(document.uri) + expect(document.positionAt).toHaveBeenNthCalledWith(1, 0) + expect(document.positionAt).toHaveBeenNthCalledWith(2, "partial model output".length) + expect(replacedText).toBe("the content the file held before this write") + }) + + it("line 833: falls back to an empty buffer text, not a placeholder string, when a new-file rollback has no recorded original", async () => { + const document = makeRollbackDocument("partial model output", true, true) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "create", + createdDirs: [], + placeholderPath: undefined, + originalContent: undefined, + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + + await withTabGroupsAll([makeDirtyFileTab()], () => diffViewProvider.revertChanges()) + + // Distinct positions prove the range spans the buffer: an empty or reversed range would hand + // the Range double the same position twice, and the uri is the document being rolled back. + const [replacedUri, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedUri).toBe(document.uri) + expect(document.positionAt).toHaveBeenNthCalledWith(1, 0) + expect(document.positionAt).toHaveBeenNthCalledWith(2, "partial model output".length) + expect(replacedText).toBe("") + }) + + it("line 841: reports the unconfirmed save of the diff buffer it just restored, naming the path and the stopped work", async () => { + // applyEdit confirmed, document.save() did not: the rollback stops before any close or + // unlink, and the report is the only thing the caller gets, so it has to carry the reason. + const document = makeRollbackDocument("partial model output", true, false) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "create", + createdDirs: [], + placeholderPath: settleTargetPath, + originalContent: "", + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + + await withTabGroupsAll([makeDirtyFileTab()], async () => { + await expect(diffViewProvider.revertChanges()).rejects.toThrowError( + new Error( + `Rollback could not save the restored buffer for ${settleTargetPath}; its clean state is unconfirmed, so the rollback stopped before closing tabs or deleting the file.`, + ), + ) + }) + + expect(vscode.window.tabGroups.close).not.toHaveBeenCalled() + expect(fs.unlink).not.toHaveBeenCalled() + }) + + it("line 883: restores the recorded content rather than an empty buffer when an existing file is rolled back", async () => { + const document = makeRollbackDocument("streamed content", false, true) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "modify", + createdDirs: [], + originalContent: "the content the file held before this write", + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["keepOrCloseEditedFile"] = vi.fn().mockResolvedValue(undefined) + + await diffViewProvider.revertChanges() + + const [, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedText).toBe("the content the file held before this write") + }) + + it("line 883: strips an empty buffer text rather than a stand-in when a modify rollback has no recorded original", async () => { + const document = makeRollbackDocument("streamed content", false, true) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "modify", + createdDirs: [], + originalContent: undefined, + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["keepOrCloseEditedFile"] = vi.fn().mockResolvedValue(undefined) + + await diffViewProvider.revertChanges() + + const [, , replacedText] = mockWorkspaceEdit.replace.mock.calls[0] + expect(replacedText).toBe("") + }) + + it("lines 896 and 901 and 902 and 904: rolls back to the centralized defaults when the task behind the rollback is gone", async () => { + // revertChanges() reads its auto-close settings through taskRef -> providerRef -> getState(). + // Any link of that chain can already be gone by the time a denial lands, and a rollback that + // throws while reading them would take the session teardown with it. It must instead fall + // back to the same defaults saveChanges() uses. + const document = makeRollbackDocument("streamed content", false, true) + const keepOrClose = vi.fn().mockResolvedValue(undefined) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "modify", + createdDirs: [], + originalContent: "original", + }) + diffViewProvider["taskRef"] = { deref: () => undefined } as unknown as WeakRef + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["keepOrCloseEditedFile"] = keepOrClose + + await diffViewProvider.revertChanges() + + const args = keepOrClose.mock.calls[0] + expect(args[0]).toBe(settleTargetPath) + expect(args[1]).toBe(false) + expect(args[2]).toBe(DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES) + expect(args[3]).toBe(DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES_AFTER_USER_EDITED) + expect(args[4]).toBe(DEFAULT_AUTO_CLOSE_ZOO_OPENED_NEW_FILES) + }) + + it("line 896: rolls back to the centralized defaults when the task no longer holds a provider", async () => { + const document = makeRollbackDocument("streamed content", false, true) + const keepOrClose = vi.fn().mockResolvedValue(undefined) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "modify", + createdDirs: [], + originalContent: "original", + }) + diffViewProvider["taskRef"] = { + deref: () => ({ providerRef: { deref: () => undefined } }), + } as unknown as WeakRef + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["keepOrCloseEditedFile"] = keepOrClose + + await diffViewProvider.revertChanges() + + const args = keepOrClose.mock.calls[0] + expect(args[2]).toBe(DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES) + expect(args[3]).toBe(DEFAULT_AUTO_CLOSE_ZOO_OPENED_FILES_AFTER_USER_EDITED) + expect(args[4]).toBe(DEFAULT_AUTO_CLOSE_ZOO_OPENED_NEW_FILES) + }) + + it("lines 902 and 904: carries the settings the state holds through the rollback path", async () => { + // The rollback path is the one the auto-close decision table never exercised: every row of + // that table drives saveChanges(). Opting in on the rollback path has to close the tab, or + // the settings would mean one thing on accept and another on deny. + const document = makeRollbackDocument("streamed content", false, true) + const closeFileTab = vi.fn().mockResolvedValue(undefined) + const showEditedFile = vi.fn().mockResolvedValue(undefined) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "modify", + createdDirs: [], + originalContent: "original", + documentWasOpen: false, + userTouchedDocument: false, + userTouchedDiffEditor: false, + }) + diffViewProvider["taskRef"] = { + deref: () => + makeTaskDouble({ + autoCloseZooOpenedFiles: true, + autoCloseZooOpenedFilesAfterUserEdited: true, + autoCloseZooOpenedNewFiles: true, + }), + } as unknown as WeakRef + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["closeFileTab"] = closeFileTab + diffViewProvider["showEditedFileWithoutDisruptingFocus"] = showEditedFile + + await diffViewProvider.revertChanges() + + expect(closeFileTab).toHaveBeenCalledWith(settleTargetPath) + expect(showEditedFile).not.toHaveBeenCalled() + }) + + it("lines 918 to 921: forwards the three settings in the slots the decision reads them from", async () => { + // The outcome of this footing cannot tell the two unreadable settings apart: with the base + // auto-close off and a modify rollback, the tab is kept whichever value the after-user-edited + // and new-files arguments hold. Only the arguments themselves can show that the values state + // holds reach keepOrCloseEditedFile in their own slots rather than as centralized defaults - + // and the two assertions below fail when a forwarded value is replaced by its default, + // while a swap of the two settings that share a value here would still pass. + const document = makeRollbackDocument("streamed content", false, true) + const keepOrClose = vi.fn().mockResolvedValue(undefined) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "modify", + createdDirs: [], + originalContent: "original", + documentWasOpen: false, + userTouchedDocument: false, + userTouchedDiffEditor: false, + }) + diffViewProvider["taskRef"] = { + deref: () => + makeTaskDouble({ + autoCloseZooOpenedFiles: false, + autoCloseZooOpenedFilesAfterUserEdited: true, + autoCloseZooOpenedNewFiles: false, + }), + } as unknown as WeakRef + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["keepOrCloseEditedFile"] = keepOrClose + + await diffViewProvider.revertChanges() + + const args = keepOrClose.mock.calls[0] + expect(args[2]).toBe(false) + expect(args[3]).toBe(true) + expect(args[4]).toBe(false) + }) + it("lines 918 to 921: pins the new-files argument in its own slot on the same unreadable footing", async () => { + // The row above sets the two settings the decision cannot read to distinct values only for the + // after-user-edited slot; autoCloseZooOpenedNewFiles shares its value with the base setting + // there, so dropping its forward would pass. Flipping only that flag here makes the same + // assertion catch it, and the two rows together pin all three arguments against being + // replaced by their centralized defaults on a path where the outcome cannot tell them apart. + const document = makeRollbackDocument("streamed content", false, true) + const keepOrClose = vi.fn().mockResolvedValue(undefined) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "modify", + createdDirs: [], + originalContent: "original", + documentWasOpen: false, + userTouchedDocument: false, + userTouchedDiffEditor: false, + }) + diffViewProvider["taskRef"] = { + deref: () => + makeTaskDouble({ + autoCloseZooOpenedFiles: false, + autoCloseZooOpenedFilesAfterUserEdited: false, + autoCloseZooOpenedNewFiles: true, + }), + } as unknown as WeakRef + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["keepOrCloseEditedFile"] = keepOrClose + + await diffViewProvider.revertChanges() + + const args = keepOrClose.mock.calls[0] + expect(args[2]).toBe(false) + expect(args[3]).toBe(false) + expect(args[4]).toBe(true) + }) + + it("lines 902 and 904: keeps the tab on the rollback path when the user touched the document and the after-user-edited setting is off", async () => { + // The touched-document branch is the only one where autoCloseZooOpenedFilesAfterUserEdited decides + // the outcome on a modify rollback, and it is the only branch where autoCloseZooOpenedNewFiles is + // unreadable. Setting the three flags to distinct values here means a wrong forwarded value moves + // the outcome: base on + after-user-edited on would close, new-files on alone would close. + const document = makeRollbackDocument("streamed content", false, true) + const closeFileTab = vi.fn().mockResolvedValue(undefined) + const showEditedFile = vi.fn().mockResolvedValue(undefined) + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "modify", + createdDirs: [], + originalContent: "original", + documentWasOpen: false, + userTouchedDocument: true, + userTouchedDiffEditor: false, + }) + diffViewProvider["taskRef"] = { + deref: () => + makeTaskDouble({ + autoCloseZooOpenedFiles: true, + autoCloseZooOpenedFilesAfterUserEdited: false, + autoCloseZooOpenedNewFiles: false, + }), + } as unknown as WeakRef + vi.mocked(vscode.workspace.applyEdit).mockResolvedValue(true) + diffViewProvider["closeAllDiffViews"] = vi.fn().mockResolvedValue(undefined) + diffViewProvider["closeFileTab"] = closeFileTab + diffViewProvider["showEditedFileWithoutDisruptingFocus"] = showEditedFile + + await diffViewProvider.revertChanges() + + expect(closeFileTab).not.toHaveBeenCalled() + expect(showEditedFile).toHaveBeenCalledWith(settleTargetPath) + }) + + it("lines 1209 and 1211: stops the rollback and reports the refused restore of the file-scheme buffer by name", async () => { + // The diff-side restore confirms; the plain file-scheme buffer holding the same unapproved + // content is the one VS Code refuses to put back. Closing it anyway would hand the user a + // save prompt over exactly the content this rollback discards. + const document = makeRollbackDocument("partial model output", true, true) + const streamedBuffer = { + uri: makeUri(settleTargetPath), + scheme: "file", + getText: vi.fn().mockReturnValue("partial model output"), + positionAt: vi.fn().mockReturnValue({ line: 0, character: 0 }), + isDirty: true, + save: vi.fn().mockResolvedValue(true), + } + Object.assign(diffViewProvider, { + relPath: settleRelPath, + activeDiffEditor: { document }, + editType: "create", + createdDirs: [], + placeholderPath: settleTargetPath, + originalContent: "", + }) + vi.mocked(vscode.workspace.applyEdit).mockResolvedValueOnce(true).mockResolvedValueOnce(false) + + await withTextDocuments([streamedBuffer], () => + withTabGroupsAll([makeDirtyFileTab()], async () => { + await expect(diffViewProvider.revertChanges()).rejects.toThrowError( + new Error( + `Rollback could not restore the buffer for ${settleTargetPath}; it may still hold unapproved content, so the tab was left open rather than closed.`, + ), + ) + }), + ) + + expect(streamedBuffer.save).not.toHaveBeenCalled() + expect(vscode.window.tabGroups.close).not.toHaveBeenCalled() + expect(fs.unlink).not.toHaveBeenCalled() + }) + + it("lines 1558 and 1559 and 1563 and 1564 and 1569 and 1570 and 1571: clears every session field the reset owns, not only the ones with a visible effect", async () => { + // A flag that survives reset() is read by the NEXT edit as if it described that edit: + // documentWasOpen decides whether the tab is restored instead of closed, the two touched + // flags decide auto-close, and streamedLines/preDiagnostics/snapshotPreviewTabs carry one + // edit's stream, diagnostics and tab snapshot into the next one. + Object.assign(diffViewProvider, { + documentWasOpen: true, + documentWasPinned: true, + streamedLines: ["leftover streamed line"], + preDiagnostics: [{ message: "leftover diagnostic" }], + userTouchedDocument: true, + userTouchedDiffEditor: true, + snapshotPreviewTabs: [makePreviewTab(`${mockCwd}/leftover-preview.ts`)], + }) + + await diffViewProvider.reset() + + expect(diffViewProvider["documentWasOpen"]).toBe(false) + expect(diffViewProvider["documentWasPinned"]).toBe(false) + expect(diffViewProvider["userTouchedDocument"]).toBe(false) + expect(diffViewProvider["userTouchedDiffEditor"]).toBe(false) + expect(diffViewProvider["streamedLines"]).toEqual([]) + expect(diffViewProvider["preDiagnostics"]).toEqual([]) + expect(diffViewProvider["snapshotPreviewTabs"]).toEqual([]) + }) + }) }) diff --git a/src/integrations/misc/__tests__/indentation-reader-unicode.spec.ts b/src/integrations/misc/__tests__/indentation-reader-unicode.spec.ts index bfc397cf09..1d41ac30f3 100644 --- a/src/integrations/misc/__tests__/indentation-reader-unicode.spec.ts +++ b/src/integrations/misc/__tests__/indentation-reader-unicode.spec.ts @@ -74,6 +74,7 @@ describe("Unicode clipping through the existing readers", () => { totalLines: 3, returnedLines: 1, wasTruncated: true, + hasClippedLines: true, }) expect(Buffer.from(result.content).toString("utf8")).toBe(result.content) }) @@ -89,6 +90,8 @@ describe("Unicode clipping through the existing readers", () => { totalLines: 3, returnedLines: 1, wasTruncated: true, + // The returned line is clipped, so the flag belongs to the result. + hasClippedLines: true, }) expect(Buffer.from(result.content).toString("utf8")).toBe(result.content) }) @@ -104,6 +107,8 @@ describe("Unicode clipping through the existing readers", () => { totalLines: 5, returnedLines: 3, wasTruncated: false, + // The block shows every line it includes, but one is clipped. + hasClippedLines: true, }) expect(Buffer.from(result.content).toString("utf8")).toBe(result.content) }) @@ -115,6 +120,7 @@ describe("Unicode clipping through the existing readers", () => { totalLines: 1, returnedLines: 1, wasTruncated: false, + hasClippedLines: true, }) expect(readWithSlice("")).toEqual({ content: "1 | ", @@ -122,6 +128,7 @@ describe("Unicode clipping through the existing readers", () => { totalLines: 1, returnedLines: 1, wasTruncated: false, + hasClippedLines: false, }) }) @@ -132,6 +139,7 @@ describe("Unicode clipping through the existing readers", () => { totalLines: 1, returnedLines: 0, wasTruncated: false, + hasClippedLines: false, }) expect(readWithIndentation(longLine, { anchorLine: 0 })).toEqual({ content: "Error: anchor_line 0 is out of range (1-1)", @@ -139,6 +147,7 @@ describe("Unicode clipping through the existing readers", () => { totalLines: 1, returnedLines: 0, wasTruncated: false, + hasClippedLines: false, }) }) }) diff --git a/src/integrations/misc/__tests__/indentation-reader.spec.ts b/src/integrations/misc/__tests__/indentation-reader.spec.ts index a092dff8fc..622a150235 100644 --- a/src/integrations/misc/__tests__/indentation-reader.spec.ts +++ b/src/integrations/misc/__tests__/indentation-reader.spec.ts @@ -1,4 +1,5 @@ import { describe, it, expect } from "vitest" +import { MAX_LINE_LENGTH } from "../../../core/prompts/tools/native-tools/read_file" import { parseLines, formatWithLineNumbers, @@ -278,11 +279,45 @@ describe("readWithSlice", () => { expect(result.wasTruncated).toBe(true) }) + it("reports a clipped line separately from omitted lines", () => { + // Every line is returned, but formatWithLineNumbers clips a line longer + // than MAX_LINE_LENGTH, so the model did not see the whole file. + const lines = ["x".repeat(MAX_LINE_LENGTH + 10), "short"].join("\n") + const result = readWithSlice(lines, 0, 10) + + expect(result.returnedLines).toBe(2) + expect(result.wasTruncated).toBe(false) + expect(result.hasClippedLines).toBe(true) + }) + + it("keeps a slice complete when a line is exactly at the length cap", () => { + // formatWithLineNumbers clips only lines strictly longer than the cap, so a + // line at exactly MAX_LINE_LENGTH is shown in full and the read is complete. + const lines = ["x".repeat(MAX_LINE_LENGTH), "short"].join("\n") + const result = readWithSlice(lines, 0, 10) + + expect(result.returnedLines).toBe(2) + expect(result.wasTruncated).toBe(false) + expect(result.hasClippedLines).toBe(false) + }) + + it("flags clipping when any line is clipped, not only when every line is", () => { + // The first line is clipped and the second is shown in full: some lines are + // a partial view even though every line was returned. + const lines = ["y".repeat(MAX_LINE_LENGTH + 1), "short"].join("\n") + const result = readWithSlice(lines, 0, 10) + + expect(result.returnedLines).toBe(2) + expect(result.hasClippedLines).toBe(true) + }) + it("should handle offset beyond file end", () => { const result = readWithSlice(SIMPLE_CODE, 1000, 10) expect(result.returnedLines).toBe(0) expect(result.content).toContain("Error: offset 1001 is beyond file end") + // No line was returned, so nothing could have been clipped. + expect(result.hasClippedLines).toBe(false) }) it("should handle negative offset", () => { @@ -296,6 +331,53 @@ describe("readWithSlice", () => { // ─── readWithIndentation Tests ──────────────────────────────────────────────── describe("readWithIndentation", () => { + it("reports an out-of-range anchor as an error with no clipping", () => { + const result = readWithIndentation(SIMPLE_CODE, { anchorLine: 1000 }) + + expect(result.content).toContain("out of range") + expect(result.returnedLines).toBe(0) + expect(result.hasClippedLines).toBe(false) + }) + + it("flags a clipped line in the single-line limit case", () => { + // finalLimit === 1 returns only the anchor line, and formatWithLineNumbers + // clips it when it exceeds the cap: the flag must still be set. + const code = ["short()", `long(${"x".repeat(MAX_LINE_LENGTH + 5)})`, "tail()"].join("\n") + const result = readWithIndentation(code, { anchorLine: 2, limit: 1 }) + + expect(result.returnedLines).toBe(1) + expect(result.hasClippedLines).toBe(true) + }) + + it("keeps the single-line limit case unflagged when the line fits the cap", () => { + // Clipping is strictly-longer-than-cap, so a line at exactly the cap is + // shown in full and the read carries no clipping flag. + const code = ["short()", `fits(${"y".repeat(MAX_LINE_LENGTH - 6)})`, "tail()"].join("\n") + const result = readWithIndentation(code, { anchorLine: 2, limit: 1 }) + + expect(result.returnedLines).toBe(1) + expect(result.hasClippedLines).toBe(false) + }) + + it("flags a clipped line inside an expanded block", () => { + // The expansion returns every line of the block, but the long one is + // clipped in the returned view: the flag must be set even with no + // omission. + const code = ["start()", `long(${"x".repeat(MAX_LINE_LENGTH + 1)})`, "end()"].join("\n") + const result = readWithIndentation(code, { anchorLine: 2, limit: 10 }) + + expect(result.returnedLines).toBeGreaterThan(1) + expect(result.hasClippedLines).toBe(true) + }) + + it("keeps an expanded block unflagged when every line fits the cap", () => { + const code = ["start()", "mid()", "end()"].join("\n") + const result = readWithIndentation(code, { anchorLine: 2, limit: 10 }) + + expect(result.returnedLines).toBeGreaterThan(1) + expect(result.hasClippedLines).toBe(false) + }) + describe("basic block extraction", () => { it("should extract content around the anchor line", () => { const result = readWithIndentation(PYTHON_CODE, { diff --git a/src/integrations/misc/indentation-reader.ts b/src/integrations/misc/indentation-reader.ts index 43e86a47ad..ff324738a3 100644 --- a/src/integrations/misc/indentation-reader.ts +++ b/src/integrations/misc/indentation-reader.ts @@ -58,8 +58,10 @@ export interface IndentationReadResult { totalLines: number /** Lines actually returned */ returnedLines: number - /** Whether output was truncated due to limit */ + /** Whether output was truncated because lines were omitted */ wasTruncated: boolean + /** Whether any returned line was clipped by the per-line length cap */ + hasClippedLines?: boolean } // ─── Constants ──────────────────────────────────────────────────────────────── @@ -244,6 +246,7 @@ export function readWithIndentation(content: string, options: IndentationReadOpt totalLines, returnedLines: 0, wasTruncated: false, + hasClippedLines: false, } } @@ -276,6 +279,9 @@ export function readWithIndentation(content: string, options: IndentationReadOpt totalLines, returnedLines: 1, wasTruncated: totalLines > 1, + // The single-line case is no exception to the clipping contract: + // formatWithLineNumbers clips this line when it exceeds the cap. + hasClippedLines: lines[anchorIdx].content.length > MAX_LINE_LENGTH, } } @@ -358,6 +364,10 @@ export function readWithIndentation(content: string, options: IndentationReadOpt totalLines, returnedLines: result.length, wasTruncated: wasTruncated && result.length < totalLines, + // The expansion path reports clipping like the slice path: a block can + // return every line it includes and still hide content behind the + // per-line length cap. + hasClippedLines: result.some((line) => line.content.length > MAX_LINE_LENGTH), } } @@ -386,6 +396,7 @@ export function readWithSlice( totalLines, returnedLines: 0, wasTruncated: false, + hasClippedLines: false, } } @@ -393,6 +404,11 @@ export function readWithSlice( const endIdx = Math.min(offset + limit, totalLines) const selectedLines = lines.slice(offset, endIdx) const wasTruncated = endIdx < totalLines + // A returned line can still be a partial view: formatWithLineNumbers clips a + // line longer than MAX_LINE_LENGTH, so a slice that returned every line may + // still hide content. Clipping is reported separately from omission so the + // caller does not suggest a next offset that is beyond the file. + const hasClippedLines = selectedLines.some((line) => line.content.length > MAX_LINE_LENGTH) // Format output const formattedContent = formatWithLineNumbers(selectedLines) @@ -403,5 +419,6 @@ export function readWithSlice( totalLines, returnedLines: selectedLines.length, wasTruncated, + hasClippedLines, } } diff --git a/src/services/file-safety/__tests__/safeWriteText.integration.spec.ts b/src/services/file-safety/__tests__/safeWriteText.integration.spec.ts new file mode 100644 index 0000000000..dbd9f3912e --- /dev/null +++ b/src/services/file-safety/__tests__/safeWriteText.integration.spec.ts @@ -0,0 +1,75 @@ +import * as fs from "fs/promises" +import * as os from "os" +import * as path from "path" + +import { safeWriteText } from "../safeWriteText" + +// No fs mocks in this file: the point is to assert what a real filesystem ends up +// holding after a publish attempt, which the mocked spec cannot show. The failure is +// provoked with real filesystem semantics rather than with a stubbed call. +describe("safeWriteText against a real filesystem", () => { + let dir: string + + beforeEach(async () => { + dir = await fs.mkdtemp(path.join(os.tmpdir(), "safe-write-text-int-")) + }) + + afterEach(async () => { + await fs.rm(dir, { recursive: true, force: true }) + }) + + it("publishes the new bytes and leaves no staging or backup residue", async () => { + const targetPath = path.join(dir, "target.txt") + await fs.writeFile(targetPath, "old bytes") + + // No platform override: the real platform's own durability and ACL steps run, and this + // case is the successful restore. Windows DACL restoration is best-effort after the + // commit rename: step 5 runs icacls /restore only once fs.rename has already put the + // staged file in the target's place, and _restoreDaclWindows swallows a failing + // restore, so the publish still resolves and only the .acl dump is unlinked. That is + // the contract asserted by "win32 DACL: dump is unlinked even when restore fails" at + // src/services/file-safety/__tests__/safeWriteText.spec.ts:829. The save side is a + // different contract: a failed icacls /save throws DaclInspectionError with phase + // "save" before any rename, which is what "win32 DACL: a partial dump left by a failed + // save is removed and the publish is refused" at safeWriteText.spec.ts:741 asserts. So + // on a machine where icacls cannot put a saved ACL back into a throwaway temp + // directory this publish still resolves and the residue assertions below are reached. + await safeWriteText(targetPath, "new bytes", { backup: true }) + + expect(await fs.readFile(targetPath, "utf8")).toBe("new bytes") + expect(await fs.readdir(dir)).toEqual(["target.txt"]) + }) + + it("leaves the target bytes untouched when the commit cannot replace it", async () => { + // A regular file cannot be renamed over a directory, so the backup copy and + // the commit both fail on a real filesystem with no mocking at all. + const targetPath = path.join(dir, "target-dir") + await fs.mkdir(targetPath) + const inside = path.join(targetPath, "payload.txt") + await fs.writeFile(inside, "original bytes") + + await expect(safeWriteText(targetPath, "new data", { backup: true })).rejects.toThrow() + + // The directory and its content are exactly as they were, and no backup copy + // or staging directory was left behind next to them. + expect(await fs.readFile(inside, "utf8")).toBe("original bytes") + expect(await fs.readdir(dir)).toEqual(["target-dir"]) + }) + + it("cleans up the staging file when the commit rename itself fails", async () => { + // With backup:false the backup step is skipped, so this is the only shape of + // this scenario that reaches Step 4: the rename of the staging FILE over the + // target DIRECTORY fails (EISDIR / ENOTDIR / EPERM depending on platform), and + // the cleanup must remove the staging file. The backup:true case above bails + // out in the backup step and never exercises the commit-failure path. + const targetPath = path.join(dir, "target-dir") + await fs.mkdir(targetPath) + const inside = path.join(targetPath, "payload.txt") + await fs.writeFile(inside, "original bytes") + + await expect(safeWriteText(targetPath, "new data", { backup: false })).rejects.toThrow() + + expect(await fs.readFile(inside, "utf8")).toBe("original bytes") + expect(await fs.readdir(dir)).toEqual(["target-dir"]) + }) +}) diff --git a/src/services/file-safety/__tests__/safeWriteText.spec.ts b/src/services/file-safety/__tests__/safeWriteText.spec.ts new file mode 100644 index 0000000000..855884a237 --- /dev/null +++ b/src/services/file-safety/__tests__/safeWriteText.spec.ts @@ -0,0 +1,2505 @@ +import * as fs from "fs/promises" +import type { BigIntStats } from "fs" +import * as fsSync from "fs" +import { execFile } from "child_process" +import type { ChildProcess } from "child_process" +import * as path from "path" + +import { + PostCommitDurabilityError, + DaclInspectionError, + resolveLockKey, + safeWriteText, + StagingPathError, + TargetExistsError, + UnsupportedFilesystemError, + TargetMovedError, + AncestorReplacedError, + PublishCancelledError, + OrphanedBackupAfterFailedWriteError, + OrphanedBackupError, + OrphanedPublishedBackupError, +} from "../safeWriteText" + +// Full mock for fs/promises — all methods are vi.fn() stubs +vi.mock("fs/promises", () => ({ + mkdir: vi.fn(), + access: vi.fn(), + rename: vi.fn(), + link: vi.fn(), + copyFile: vi.fn(), + chmod: vi.fn(), + unlink: vi.fn(), + rmdir: vi.fn(), + realpath: vi.fn(), + stat: vi.fn(), + lstat: vi.fn(), + readlink: vi.fn(), +})) + +// Full mock for fs — all sync methods are vi.fn() stubs. Stats is a bare +// class stub so tests can build minimal Stats stand-ins via its prototype. +vi.mock("fs", () => ({ + // Mirrors Node's value; the no-replace fallback passes it to copyFile. + constants: { COPYFILE_EXCL: 1 }, + openSync: vi.fn(), + writeSync: vi.fn(), + closeSync: vi.fn(), + mkdirSync: vi.fn(), + fsyncSync: vi.fn(), + chmodSync: vi.fn(), + fchmodSync: vi.fn(), + fchownSync: vi.fn(), + statSync: vi.fn(), + Stats: class Stats {}, +})) + +// Mock child_process.execFile (callback-based — must invoke callback to resolve) +vi.mock("child_process", () => ({ + execFile: vi.fn((cmd, args, opts, cb) => { + if (typeof cb === "function") cb(null) + }), +})) + +// Minimal stand-in for the ChildProcess that callback-form execFile returns. +const fakeChild = { kill: () => true } as unknown as ChildProcess + +// Helper that mirrors safeWriteText's path resolution exactly +function _resolvedTarget(filePath: string): string { + return path.resolve(filePath) +} +function _dirPath(filePath: string): string { + return path.dirname(_resolvedTarget(filePath)) +} +// Minimal Stats stand-in: the SUT only reads `.mode` from it. +// Async lstat stand-in: the SUT only asks whether the path is a link or a file. +// Built on the Stats prototype so the mock value still satisfies fsSync.Stats. +function _fileStats(isLink: boolean): fsSync.Stats { + const s = Object.create(fsSync.Stats.prototype) as fsSync.Stats + s.isSymbolicLink = () => isLink + s.isFile = () => !isLink + return s +} + +function mockDefaults(): void { + vi.resetAllMocks() + // After resetAllMocks, vi.fn() returns undefined — restore promise defaults. + vi.mocked(fs.mkdir).mockResolvedValue(undefined) + vi.mocked(fs.access).mockResolvedValue(undefined) + vi.mocked(fs.rename).mockResolvedValue(undefined) + vi.mocked(fs.link).mockResolvedValue(undefined) + vi.mocked(fs.unlink).mockResolvedValue(undefined) + vi.mocked(fs.rmdir).mockResolvedValue(undefined) + // Existing-target default: a regular 0o644 file. + vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o644)) + // Staged-file default: a regular file, not a link, so a caller-supplied + // tempPath passes the location and file-type check by default. + vi.mocked(fs.lstat).mockResolvedValue(_fileStats(false)) + // Ancestor-identity pin: default to one stable directory identity so the pin + // passes unless a test overrides it. + vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(100n)) +} + +// BigIntStats stand-in for the ancestor pin: the SUT reads only dev/ino off it. +// BigIntStats is class-backed with no public constructor, so this is a +// last-resort double assertion (test-local, per AGENTS.md). +function _dirIdentity(ino: bigint): BigIntStats { + return { dev: 1n, ino } as unknown as BigIntStats +} +// BigIntStats stand-in for a regular staging file: the SUT reads dev/ino off it and asks +// whether it is a link. Same last-resort double assertion as _dirIdentity, test-local. +function _fileIdentity(dev: bigint, ino: bigint): BigIntStats { + return { dev, ino, isSymbolicLink: () => false, isFile: () => true } as unknown as BigIntStats +} +function _stats(mode: number): fsSync.Stats { + const s = Object.create(fsSync.Stats.prototype) as fsSync.Stats + Object.assign(s, { mode }) + return s +} + +// ── Test 1: staging file created then cleaned after success ──────────────── + +describe("safeWriteText", () => { + beforeEach(() => { + mockDefaults() + // Default sync-write behaviour: report that all requested bytes were + // written. The Buffer overload passes (fd, buffer, offset, length), + // so the fourth argument is the requested length. + vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) => + typeof args[3] === "number" ? args[3] : 0, + ) + }) + + describe("staging and cleanup", () => { + it("creates a temp file in the staging dir, fsyncs it, renames to target, and cleans up on success", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) // fd=1 + vi.mocked(fsSync.closeSync).mockReturnValue(undefined) + + await safeWriteText(targetPath, "hello world", { platform: "linux" }) + + // staging dir was created with private permissions — use + // stringContaining to handle Windows path resolution + expect(fsSync.mkdirSync).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"), { + recursive: true, + mode: 0o700, + }) + // a pre-existing staging dir is repaired to private permissions too + expect(fsSync.chmodSync).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"), 0o700) + + // temp file was opened for writing with the existing target's mode + // (default 0o644 from the statSync default mock) + expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), "w", 0o644) + + // content was written as a buffer (partial-write loop, full write) + expect(fsSync.writeSync).toHaveBeenCalledWith(1, Buffer.from("hello world", "utf8"), 0, 11) + + // fsync (sync form) was called on the fd + expect(fsSync.fsyncSync).toHaveBeenCalledWith(1) + + // file was closed + expect(fsSync.closeSync).toHaveBeenCalledWith(1) + + // atomic rename happened — realpath mock returns targetPath, so that's the dest + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + + // no unlink of temp (it's now the committed file; DACL skipped via platform:linux) + expect(fs.unlink).not.toHaveBeenCalled() + }) + + it("removes the now-empty staging directory after a successful self-staged commit", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "hello", { platform: "linux" }) + + // the staging subdir is removed best-effort after the commit rename + // (stringContaining: the SUT and the test helper resolve Windows + // drive-relative paths differently, as in the existing staging tests) + expect(fs.rmdir).toHaveBeenCalledTimes(1) + expect(fs.rmdir).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging")) + // the win32 DACL restore gate must stay closed on other platforms: + // no icacls save or restore is attempted + expect(execFile).not.toHaveBeenCalled() + }) + + it("still removes the staging directory when no options are supplied at all", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + // options is undefined: the self-staged check and the optional-chained + // DACL runner lookup must not dereference it + await expect(safeWriteText(targetPath, "hello")).resolves.toBeUndefined() + + expect(fs.rmdir).toHaveBeenCalledTimes(1) + expect(fs.rmdir).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging")) + if (process.platform === "win32") { + // default platform is win32: the DACL save + restore still ran + // through the default icacls path (options?.execFileRunner must + // not throw when options is undefined) + expect(vi.mocked(execFile)).toHaveBeenCalledTimes(2) + expect(vi.mocked(fs.unlink)).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl")) + } + }) + + it("does not remove the staging directory when the caller supplies its own tempPath", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const callerTemp = "/tmp/test-dir/caller-staged.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "hello", { platform: "linux", tempPath: callerTemp }) + + // the caller owns its temp file's directory; safeWriteText must not + // rmdir a directory it did not create + expect(fs.rmdir).not.toHaveBeenCalled() + }) + + it("a failed staging-dir removal never fails the committed write", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + vi.mocked(fs.rmdir).mockRejectedValue(Object.assign(new Error("ENOTEMPTY"), { code: "ENOTEMPTY" })) + + await expect(safeWriteText(targetPath, "hello", { platform: "linux" })).resolves.toBeUndefined() + + // the commit rename still happened and the rmdir error was swallowed + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"), targetPath) + expect(fs.rmdir).toHaveBeenCalledTimes(1) + expect(fs.rmdir).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging")) + }) + + it("gives each self-staged write its own staging directory so a concurrent write cannot remove it", async () => { + const targetA = "/tmp/test-dir/target-a.txt" + const targetB = "/tmp/test-dir/target-b.txt" + vi.mocked(fs.realpath).mockImplementation((p) => Promise.resolve(p as string)) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetA, "a", { platform: "linux" }) + await safeWriteText(targetB, "b", { platform: "linux" }) + + // Two self-staged writes in the same directory must not share one staging + // directory: the first write's best-effort rmdir would otherwise delete the + // directory the second write had created but not yet opened (ENOENT on openSync). + const created = vi.mocked(fsSync.mkdirSync).mock.calls.map((c) => String(c[0])) + const staging = created.filter((p) => p.includes(".file-safety-staging_")) + expect(staging).toHaveLength(2) + expect(staging[0]).not.toBe(staging[1]) + // Uniqueness comes from the documented name shape + // /.file-safety-staging__: pinning the shape + // keeps the separator and the random suffix meaningful, not just the prefix. + for (const dir of staging) { + expect(dir).toMatch(/\.file-safety-staging_\d+_[a-z0-9]+$/) + } + const removed = vi.mocked(fs.rmdir).mock.calls.map((c) => String(c[0])) + expect(removed).toEqual([staging[0], staging[1]]) + }) + + it("removes its own staging directory when a self-staged write fails", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + vi.mocked(fs.rename).mockRejectedValue(Object.assign(new Error("EACCES"), { code: "EACCES" })) + + await expect(safeWriteText(targetPath, "hello", { platform: "linux" })).rejects.toThrow("EACCES") + + // The failed write's temp file is unlinked, then the directory it + // created is removed — a failed write must not leave an empty + // .file-safety-staging directory behind. + // mkdirSync created this write's staging directory; the temp file lives + // inside it, so the unlink targets a path under that directory. + const staging = vi.mocked(fsSync.mkdirSync).mock.calls.map((c) => String(c[0])) + expect(staging).toHaveLength(1) + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining(staging[0])) + expect(fs.rmdir).toHaveBeenCalledWith(staging[0]) + // The directory is only empty after its temp file is gone, so the + // unlink must happen before the rmdir. + expect(vi.mocked(fs.unlink).mock.invocationCallOrder[0]).toBeLessThan( + vi.mocked(fs.rmdir).mock.invocationCallOrder[0], + ) + }) + + it("does not remove a staging directory it did not create when a caller-staged write fails", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const callerTemp = "/tmp/test-dir/caller-staged.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + vi.mocked(fs.rename).mockRejectedValue(Object.assign(new Error("EACCES"), { code: "EACCES" })) + + await expect( + safeWriteText(targetPath, "hello", { platform: "linux", tempPath: callerTemp }), + ).rejects.toThrow("EACCES") + + // The caller owns that directory: only the caller's temp file is cleaned, + // never a rmdir of a directory safeWriteText never created. + expect(fs.unlink).toHaveBeenCalledWith(callerTemp) + expect(fs.rmdir).not.toHaveBeenCalled() + }) + }) + + // ── Test 2: fsync ordering ─────────────────────────────────────────────── + + describe("fsync ordering", () => { + it("calls fsync on the fd before close, and rename after close", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "data", { platform: "linux" }) + + // Verify call order: openSync(temp) → writeSync → fsyncSync(temp) + // → closeSync(temp) → rename. On POSIX the parent directory is then + // opened and fsynced after the commit rename, so openSync/fsyncSync/ + // closeSync each have a second (directory) call. + expect(vi.mocked(fsSync.openSync).mock.calls.length).toBe(2) + expect(vi.mocked(fsSync.writeSync).mock.calls.length).toBe(1) + expect(vi.mocked(fsSync.fsyncSync).mock.calls.length).toBe(2) + expect(vi.mocked(fsSync.closeSync).mock.calls.length).toBe(2) + + // the temp file was fully closed before the commit rename + expect(vi.mocked(fsSync.closeSync).mock.calls[0][0]).toBe(1) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + // The title promises the order, so compare the invocations rather than + // only count them: a rename before closeSync, or a close before fsync, + // would not be a durable commit. + const fsyncOrder = vi.mocked(fsSync.fsyncSync).mock.invocationCallOrder[0] + const closeOrder = vi.mocked(fsSync.closeSync).mock.invocationCallOrder[0] + const renameOrder = vi.mocked(fs.rename).mock.invocationCallOrder[0] + expect(fsyncOrder).toBeLessThan(closeOrder) + expect(closeOrder).toBeLessThan(renameOrder) + }) + }) + + // ── Test 3: simulated failure between write and rename leaves target intact ── + + describe("crash/torn-write safety", () => { + it("simulated failure between fsync and rename leaves the target byte-identical and no temp left behind", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + vi.mocked(fs.rename).mockRejectedValue(new Error("ENOSPC")) + + await expect(safeWriteText(targetPath, "new data", { platform: "linux" })).rejects.toThrow("ENOSPC") + + // rename was attempted (the failure point) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + + // temp file was cleaned up on failure + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + + // backup was NOT created (backup:false by default), so target is untouched + // The only rename call was temp→target, not a rollback rename + expect(fs.rename).toHaveBeenCalledTimes(1) + }) + + it("a post-commit backup cleanup failure is non-fatal: the target stays committed and no temp is left behind", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // The post-commit backup unlink (SUT step 6) fails — the write must + // still succeed; an orphaned backup is the documented acceptable + // outcome, so the failure is swallowed instead of rolling back. + vi.mocked(fs.unlink).mockRejectedValueOnce(new Error("EPERM")) + + await safeWriteText(targetPath, "data", { backup: true, platform: "linux" }) + + // the commit rename (temp -> target) still happened; it is the only rename + expect(fs.rename).toHaveBeenCalledTimes(1) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + + // the failing cleanup was the post-commit backup unlink + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_")) + + // the staging temp was already committed by the rename; nothing + // temp-shaped is unlinked afterwards + expect(fs.unlink).not.toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + }) + }) + + // ── Test 4: backup:true keeps old safeWriteJson semantics incl. rollback ── + + describe("backup:true", () => { + it("copies target -> backup before commit without moving the target, deletes the copy on success", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "new data", { backup: true }) + + // target was accessed (exists check) + expect(fs.access).toHaveBeenCalledWith(targetPath) + + // The backup is a copy: the canonical target is never moved away, so readers + // never see a missing file and no later step can clobber a concurrent publish. + expect(fs.copyFile).toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_")) + expect(fs.rename).not.toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_")) + + // the only rename is the atomic commit temp -> target + expect(fs.rename).toHaveBeenCalledTimes(1) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + + // backup copy was deleted on success + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_")) + }) + + it("a failed commit does not move the target, so nothing has to be rolled back", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // The commit rename is the only rename in the flow and it fails. + vi.mocked(fs.rename).mockRejectedValue(new Error("ENOSPC")) + + await expect(safeWriteText(targetPath, "new data", { backup: true })).rejects.toThrow("ENOSPC") + + // The target never left its path, so there is no restore rename and the + // pre-write content is still what a reader sees at targetPath. + expect(fs.rename).toHaveBeenCalledTimes(1) + expect(fs.copyFile).toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_")) + + // Both the backup copy and the staging temp are cleaned up on failure. + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_")) + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + }) + + it("retries the post-commit backup removal and succeeds when the retry clears", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const backupUnlinks: string[] = [] + vi.mocked(fs.unlink).mockImplementation(async (candidate: unknown) => { + const asString = String(candidate) + if (asString.includes("safeWriteText.bak_")) { + backupUnlinks.push(asString) + // The first attempt hits a transient Windows handle; the retry succeeds. + if (backupUnlinks.length === 1) { + throw Object.assign(new Error("EBUSY"), { code: "EBUSY" }) + } + } + }) + + await safeWriteText(targetPath, "new data", { backup: true }) + + expect(backupUnlinks).toHaveLength(2) + }) + + it("surfaces an orphaned pre-write copy instead of returning success", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + vi.mocked(fs.unlink).mockImplementation(async (candidate: unknown) => { + if (String(candidate).includes("safeWriteText.bak_")) { + throw Object.assign(new Error("EPERM"), { code: "EPERM" }) + } + }) + + const error = await safeWriteText(targetPath, "new data", { backup: true }).catch( + (caught: unknown) => caught, + ) + + expect(error).toBeInstanceOf(OrphanedPublishedBackupError) + const orphan = error as OrphanedPublishedBackupError + expect(orphan.orphanedBackupPath).toContain("safeWriteText.bak_") + expect(orphan.publishedPath).toBe(targetPath) + // Two attempts, then the failure is reported instead of swallowed. + expect( + vi.mocked(fs.unlink).mock.calls.filter((call) => String(call[0]).includes("safeWriteText.bak_")), + ).toHaveLength(2) + }) + + it("creates the backup privately before its content exists, then fsyncs it", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "new data", { backup: true }) + + // The destination must exist with a private mode before copyFile writes anything + // into it: copyFile chooses the destination mode itself, so a restrictive target + // could otherwise leave a group/world-readable copy that a later chmod cannot + // undo. "wx" also means a pre-existing path is never silently reused. + const seedOpen = vi.mocked(fsSync.openSync).mock.calls.find(function (call) { + return String(call[0]).includes("safeWriteText.bak_") && call[1] === "wx" + }) + expect(seedOpen).toBeDefined() + expect(seedOpen?.[2]).toBe(0o600) + const seedOrder = vi.mocked(fsSync.openSync).mock.invocationCallOrder[ + vi.mocked(fsSync.openSync).mock.calls.indexOf(seedOpen!) + ] + expect(seedOrder).toBeLessThan(vi.mocked(fs.copyFile).mock.invocationCallOrder[0]) + + // The chmod keeps a copied read-only attribute (Windows) from breaking the fsync + // open, and keeps a backup of a permissive file private. + expect(fs.copyFile).toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_")) + expect(fs.chmod).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"), 0o600) + expect(vi.mocked(fs.chmod).mock.invocationCallOrder[0]).toBeGreaterThan( + vi.mocked(fs.copyFile).mock.invocationCallOrder[0], + ) + + // The copy is then opened for fsync with the writable flag. + const backupOpen = vi.mocked(fsSync.openSync).mock.calls.find(function (call) { + return String(call[0]).includes("safeWriteText.bak_") && call[1] === "r+" + }) + expect(backupOpen).toBeDefined() + }) + + it("a failed backup flush is reported and leaves no partial backup behind", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // The copy lands, but the fsync of the copy fails: the retained content is not + // known to be durable, so the write must not proceed on a half-written backup. + // The staged temp is fsynced earlier with a different handle, so target the + // backup's fd specifically. + vi.mocked(fsSync.openSync).mockImplementation((p: unknown) => + String(p).includes("safeWriteText.bak_") ? 7 : 1, + ) + vi.mocked(fsSync.fsyncSync).mockImplementation((fd: unknown) => { + if (fd === 7) { + throw new Error("EIO") + } + }) + + await expect(safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })).rejects.toThrow( + "EIO", + ) + + // Nothing was published, and the incomplete copy is removed rather than left + // next to the target looking like a usable backup. + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_")) + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + }) + + it("carries the leftover path when the partial backup cannot be removed either", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockImplementation((p: unknown) => + String(p).includes("safeWriteText.bak_") ? 7 : 1, + ) + vi.mocked(fsSync.fsyncSync).mockImplementation((fd: unknown) => { + if (fd === 7) { + throw new Error("EIO") + } + }) + let unlinkAttempts = 0 + vi.mocked(fs.unlink).mockImplementation(async (p: unknown) => { + if (String(p).includes("safeWriteText.bak_")) { + unlinkAttempts++ + } + throw Object.assign(new Error("EPERM"), { code: "EPERM" }) + }) + + // The copy failed and the locked leftover could not be unlinked even after the + // retry. Dropping the path would leave a partial copy of the previous content on + // disk with no reference to it anywhere, so the error carries it. + const error = await safeWriteText(targetPath, "new data", { + backup: true, + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(OrphanedBackupError) + const orphan = error as OrphanedBackupError + expect(orphan.orphanedBackupPath).toContain("safeWriteText.bak_") + expect(orphan.message).toContain("safeWriteText.bak_") + expect(orphan.message).toContain("EPERM") + expect(orphan.originalError).toBeInstanceOf(Error) + expect((orphan.originalError as Error).message).toBe("EIO") + expect(orphan.cause).toBe(orphan.originalError) + expect(unlinkAttempts).toBe(2) + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("refuses a backup name another writer already owns instead of unlinking it", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + // The exclusive seed open hits a backup name this write never created. + vi.mocked(fsSync.openSync).mockImplementation((...args: unknown[]) => { + if (typeof args[0] === "string" && args[0].includes("safeWriteText.bak_")) { + throw Object.assign(new Error("EEXIST"), { code: "EEXIST" }) + } + return 1 + }) + + const error = await safeWriteText(targetPath, "new data", { + backup: true, + platform: "linux", + }).catch((caught: unknown) => caught) + + expect((error as Error).message).toContain("EEXIST") + // The name is not this write's orphan: unlinking it on the way out would + // delete another writer's backup to clean up a file this write never made. + const backupUnlinks = vi.mocked(fs.unlink).mock.calls.filter(function (call: unknown[]) { + return typeof call[0] === "string" && call[0].includes("safeWriteText.bak_") + }) + expect(backupUnlinks).toHaveLength(0) + expect(fs.copyFile).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("reports a backup copy it cannot remove after a failed write instead of dropping it", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // The copy is seeded and flushed fine; only its removal on the failure + // path fails, twice, with the same handle-not-released error Windows + // reports for a fresh file. + vi.mocked(fs.unlink).mockImplementation(async (p: unknown) => { + if (String(p).includes("safeWriteText.bak_")) { + throw Object.assign(new Error("EPERM"), { code: "EPERM" }) + } + }) + // The commit is what fails here, so nothing was published. + vi.mocked(fs.rename).mockRejectedValue(Object.assign(new Error("EIO"), { code: "EIO" })) + + const error = await safeWriteText(targetPath, "new data", { + backup: true, + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(OrphanedBackupAfterFailedWriteError) + const orphan = error as OrphanedBackupAfterFailedWriteError + expect(orphan.orphanedBackupPath).toContain("safeWriteText.bak_") + expect(orphan.message).toContain("safeWriteText.bak_") + expect(orphan.message).toContain("EPERM") + // The write's own failure stays the primary fact: it travels as + // originalError and as the cause, and cleanupError says why the copy + // is still on disk. + expect((orphan.originalError as Error).message).toBe("EIO") + expect((orphan.cleanupError as Error).message).toBe("EPERM") + expect(orphan.cause).toBe(orphan.originalError) + // The commit never succeeded, so the target still holds the previous + // content and the copy duplicates it rather than going stale. + expect(orphan.contentPublished).toBe(false) + const backupUnlinks = vi.mocked(fs.unlink).mock.calls.filter(function (call: unknown[]) { + return typeof call[0] === "string" && call[0].includes("safeWriteText.bak_") + }) + expect(backupUnlinks).toHaveLength(2) + // Reporting the leftover must not skip cleaning the write's own staged + // file and staging directory: both ran before the leftover was reported. + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + expect(fs.rmdir).toHaveBeenCalled() + }) + + it("a backup copy that fails part-way is removed, not left as a usable-looking backup", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // The destination is seeded with openSync("wx") BEFORE any content exists at it, + // and the copy then fails part-way: the name is there, holding a partial copy of + // nothing usable. Cleanup has to key off the attempt, not off a copy that + // succeeded, or this file outlives the failed write beside the target. + vi.mocked(fs.copyFile).mockRejectedValue(Object.assign(new Error("EIO"), { code: "EIO" })) + + await expect(safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })).rejects.toThrow( + "EIO", + ) + + // Nothing was published, and the half-written copy is removed rather than left + // next to the target looking like a backup someone could restore. + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_")) + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + }) + + it("backup:true when target does not exist: no backup created, just commit", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // fs.access resolves for dirPath check, but rejects for target check (backup path) + vi.mocked(fs.access).mockImplementation(async (p) => { + if (typeof p === "string" && p.endsWith("target.txt")) throw { code: "ENOENT" } + }) + + await safeWriteText(targetPath, "new data", { backup: true, platform: "linux" }) + + // no backup rename (target didn't exist) + expect(fs.access).toHaveBeenCalledWith(targetPath) + + // only one rename: temp -> target + expect(fs.rename).toHaveBeenCalledTimes(1) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + + // no unlink (no backup to delete; DACL skipped via platform:linux) + expect(fs.unlink).not.toHaveBeenCalled() + }) + }) + + // ── Test 5: win32 DACL path ────────────────────────────────────────────── + + describe("win32 DACL", () => { + it.skipIf(process.platform !== "win32")( + "copies target DACL onto staging file via icacls before rename on Windows", + async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + await safeWriteText(targetPath, "data", { platform: "win32" }) + + // icacls dump + restore were called (execFile is callback-based mock) + expect(execFile).toHaveBeenCalledTimes(2) + }, + ) + + it("non-win32: DACL path is unreachable when platform is not win32", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "data", { platform: "linux" }) + + // icacls was NOT called on non-win32 + expect(execFile).not.toHaveBeenCalled() + }) + + it("win32 DACL failure refuses the publish instead of renaming over the target", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // icacls dump fails — the callback-based mock must invoke cb with an error. + vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => { + if (typeof cb === "function") cb(new Error("icacls error"), "", "") + return fakeChild + }) + + // Captured once: calling safeWriteText twice here would double-count the single + // icacls attempt asserted below. + const refusal = await safeWriteText(targetPath, "data", { platform: "win32" }).catch( + (error: unknown) => error, + ) + + expect(refusal).toBeInstanceOf(DaclInspectionError) + // The class alone does not pin the contract: swapping the phase or dropping the + // target path still satisfies toBeInstanceOf, and both are caller-visible - the + // phase says which check refused, the path names the file the caller must not + // assume was saved. + expect(refusal).toMatchObject({ + name: "DaclInspectionError", + phase: "save", + targetPath, + message: expect.stringContaining("its DACL could not be saved"), + }) + + // The refusal names the phase and the path but not what icacls did. The + // platform failure travels on the error so a caller can tell a refused + // icacls from an icacls that could not be started at all. + const cause = (refusal as DaclInspectionError).causeError + expect(cause).toBeInstanceOf(Error) + expect((cause as Error).message).toBe("icacls error") + + // Contract change (Security Boundaries row): a target whose DACL could not be + // saved is no longer replaced by a file that inherits different rights. + expect(fs.rename).not.toHaveBeenCalled() + // one icacls attempt only: a failed capture must not try to restore + expect(execFile).toHaveBeenCalledTimes(1) + }) + + it("win32 DACL: a partial dump left by a failed save is removed and the publish is refused", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // icacls save fails - a real icacls may have written a partial dump + // before erroring, so the dump path must be cleaned up and must never + // be used for a restore. + vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => { + if (typeof cb === "function") cb(new Error("icacls save error"), "", "") + return fakeChild + }) + + const refusal = await safeWriteText(targetPath, "data", { platform: "win32" }).catch( + (error: unknown) => error, + ) + + // The contract changed with the refusal: a target whose DACL could not be captured is + // not replaced by a file that inherits different rights, so no rename happens at all. + expect(refusal).toBeInstanceOf(DaclInspectionError) + expect(refusal).toMatchObject({ name: "DaclInspectionError", phase: "save", targetPath }) + expect(fs.rename).not.toHaveBeenCalled() + expect(execFile).toHaveBeenCalledTimes(1) + const saveArgs = vi.mocked(execFile).mock.calls[0]?.[1] + expect(saveArgs?.[1]).toBe("/save") + // the dump path (possibly partially created by icacls) was unlinked + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl")) + }) + it("win32: refuses the publish when the target exists but its access rights cannot be read", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // The target exists but is not readable: that is not "absent", and skipping DACL + // preservation has to stop the publish rather than be reported beside it. + vi.mocked(fs.access).mockImplementation(async (p) => { + if (String(p) === targetPath) { + throw Object.assign(new Error("EACCES"), { code: "EACCES" }) + } + return undefined + }) + + // Captured once: a second call would double-count the assertions below. + const refusal = await safeWriteText(targetPath, "data", { platform: "win32" }).catch( + (error: unknown) => error, + ) + + expect(refusal).toBeInstanceOf(DaclInspectionError) + // The class alone does not pin the contract: the phase says which check refused and + // the path names the file the caller must not assume was saved. + expect(refusal).toMatchObject({ + name: "DaclInspectionError", + phase: "inspect", + targetPath, + message: expect.stringContaining("its access rights could not be checked"), + }) + + // The publish is refused before any icacls runs, and nothing is renamed. + expect(execFile).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("win32 DACL save args are [targetPath, /save, dumpPath, /T] before backup rename", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "data", { backup: true, platform: "win32" }) + + // icacls was called twice (save + restore) + expect(execFile).toHaveBeenCalledTimes(2) + + // First call: save DACL from target before backup rename + const firstCall = vi.mocked(execFile).mock.calls[0] + expect(firstCall[0]).toBe("icacls") + expect(firstCall[1]).toEqual([targetPath, "/save", expect.stringContaining("safeWriteText.acl"), "/T"]) + + // Second call: restore DACL onto directory after commit rename + const secondCall = vi.mocked(execFile).mock.calls[1] + expect(secondCall[0]).toBe("icacls") + expect(secondCall[1]).toEqual([ + expect.stringContaining("/tmp/test-dir"), + "/restore", + expect.stringContaining("safeWriteText.acl"), + ]) + + // dump file was unlinked after restore + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl")) + }) + + it("win32 DACL: dump is unlinked even when restore fails", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + // icacls save succeeds, restore fails + let callCount = 0 + vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => { + callCount++ + if (typeof cb === "function") { + cb(callCount === 1 ? null : new Error("icacls restore error"), "", "") + } + return fakeChild + }) + + await safeWriteText(targetPath, "data", { platform: "win32" }) + + // write succeeded despite restore failure (best-effort) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + expect(fs.rename).toHaveBeenCalledTimes(1) + + // dump file was still unlinked in finally + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl")) + }) + + it("win32 DACL: when target does not exist, no save/restore/dump", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + // fs.access rejects for targetPath (ENOENT), but resolves for dirPath + vi.mocked(fs.access).mockImplementation(async (p) => { + if (typeof p === "string" && p.endsWith("target.txt")) throw { code: "ENOENT" } + return undefined + }) + + await safeWriteText(targetPath, "data", { platform: "win32" }) + + // icacls was NOT called (target absent → skip DACL entirely) + expect(execFile).not.toHaveBeenCalled() + + // no dump file created or unlinked + expect(fs.unlink).not.toHaveBeenCalled() + }) + }) + + // ── Test 6: pre-written temp path (tempPath option) ────────────────────── + + describe("pre-written temp path", () => { + it("uses the provided tempPath, fsyncs it, and renames to target", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + const customTempPath = "/tmp/test-dir/custom-temp.tmp" + + // platform:linux skips DACL entirely so this test focuses on tempPath only + await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" }) + + // openSync was called on the custom temp path (r+ mode for fsync) + expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+") + + // fsync was called + expect(fsSync.fsyncSync).toHaveBeenCalledWith(1) + + // rename happened — realpath mock returns targetPath + expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath) + + // no unlink of custom temp (caller's concern; DACL skipped via platform:linux) + expect(fs.unlink).not.toHaveBeenCalled() + + // a caller-supplied tempPath must not create the staging directory + expect(fsSync.mkdirSync).not.toHaveBeenCalled() + }) + + it("applies the existing target's mode to a caller-supplied tempPath before publishing", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o600)) + vi.mocked(fsSync.openSync).mockReturnValue(2) + + const customTempPath = "/tmp/test-dir/custom-temp.tmp" + + await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" }) + + // the caller-staged temp is fchmod'd to the restrictive target mode so + // the atomic rename cannot widen a 0o600 target (CWE-732 regression) + expect(fsSync.fchmodSync).toHaveBeenCalledWith(2, 0o600) + expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+") + expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath) + }) + + it("keeps the temp's default mode when the target does not exist yet (ENOENT)", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fsSync.statSync).mockImplementation(() => { + throw enoent + }) + vi.mocked(fsSync.openSync).mockReturnValue(2) + + const customTempPath = "/tmp/test-dir/custom-temp.tmp" + + await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" }) + + // no existing target, so nothing to preserve and no fchmod on the temp + expect(fsSync.fchmodSync).not.toHaveBeenCalled() + expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath) + }) + + it("propagates a non-ENOENT stat failure rather than defaulting the mode (caller-staged)", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + vi.mocked(fsSync.statSync).mockImplementation(() => { + throw eacces + }) + vi.mocked(fsSync.openSync).mockReturnValue(2) + + const customTempPath = "/tmp/test-dir/custom-temp.tmp" + + // A target that cannot be stat'd is not a fresh target: publishing with + // the default mode would widen a restrictive target through the rename. + await expect( + safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" }), + ).rejects.toThrow("EACCES") + expect(fsSync.fchmodSync).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("propagates a non-ENOENT stat failure rather than defaulting the mode (self-staged)", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + const eio = Object.assign(new Error("EIO: i/o error"), { code: "EIO" }) + vi.mocked(fsSync.statSync).mockImplementation(() => { + throw eio + }) + + // The mode is read before the temp is opened, so a real I/O failure stops + // the write before anything is staged. + await expect(safeWriteText(targetPath, "hello world", { platform: "linux" })).rejects.toThrow("EIO") + expect(fsSync.openSync).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("opens the temp before applying a read-only target's mode (0o444 does not block the open)", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o444)) + vi.mocked(fsSync.openSync).mockReturnValue(3) + + const customTempPath = "/tmp/test-dir/custom-temp.tmp" + + await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" }) + + // a 0o444 target must not make openSync(tempPath, "r+") fail: the mode + // is applied with fchmodSync on the already-open fd, after the open + expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+") + expect(fsSync.fchmodSync).toHaveBeenCalledWith(3, 0o444) + const openIdx = vi.mocked(fsSync.openSync).mock.invocationCallOrder[0] + const fchmodIdx = vi.mocked(fsSync.fchmodSync).mock.invocationCallOrder[0] + expect(openIdx).toBeLessThan(fchmodIdx) + expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath) + }) + + it("applies the existing target's exact mode to the self-staged temp (umask must not narrow it)", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o664)) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "data", { platform: "linux" }) + + // openSync's creation mode is narrowed by the process umask (0o664 -> 0o644 with + // the common 0o022), and the rename publishes the temp's mode onto the target, + // so the existing target's mode must be applied on the fd before the commit. + expect(fsSync.fchmodSync).toHaveBeenCalledWith(1, 0o664) + const openIdx = vi.mocked(fsSync.openSync).mock.invocationCallOrder[0] + const fchmodIdx = vi.mocked(fsSync.fchmodSync).mock.invocationCallOrder[0] + expect(openIdx).toBeLessThan(fchmodIdx) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + }) + + it("a failed post-commit directory fsync does not roll the backup back over the published content", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const dirPath = path.dirname(targetPath) + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + // The file fd opens normally; the parent-directory open after the commit + // rename fails, which is the post-commit durability failure. + vi.mocked(fsSync.openSync).mockImplementation((target) => { + if (String(target) === dirPath) throw new Error("EBADF") + return 1 + }) + + await expect(safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })).rejects.toThrow( + PostCommitDurabilityError, + ) + + // The commit rename already published the new content, and the backup was only + // ever a copy: the target was never moved, so there is nothing to rename back. + expect(fs.copyFile).toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_")) + expect(fs.rename).toHaveBeenCalledTimes(1) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + + // The durability failure is reported, not swallowed - and the backup copy is not + // left beside the target where no caller could find it. + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_")) + }) + + it("does not fchmod the self-staged temp for a fresh target", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fsSync.statSync).mockImplementation(() => { + throw enoent + }) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "data", { platform: "linux" }) + + // Nothing exists to preserve: the default creation mode is the intended one. + expect(fsSync.fchmodSync).not.toHaveBeenCalled() + }) + }) + + // ── Test 7: symlink handling (Finding 4 regression test) ───────────────── + + describe("symlink handling", () => { + it("a write through a symlink commits onto the resolved referent, never the link path", async () => { + const linkPath = "/tmp/links/link.txt" + const referentPath = "/tmp/targets/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(referentPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(linkPath, "new-content", { platform: "linux" }) + + // The commit rename must target the realpath result (the referent), never the link itself — + // that is what guarantees a write through a symlink replaces the referent's content + // and preserves the link. + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), referentPath) + expect(fs.rename).not.toHaveBeenCalledWith(expect.anything(), linkPath) + }) + + it("when realpath reports ENOENT (target absent), uses the given path as-is", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" })) + // lstat reports the path itself as absent, so this is a new target and + // the fallback is allowed. + vi.mocked(fs.lstat).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" })) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "data", { platform: "linux" }) + + // rename still happened with the fallback path (path.resolve on /tmp → C:\tmp) + const resolvedFallback = _resolvedTarget(targetPath) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), resolvedFallback) + }) + + it("propagates a dangling symlink instead of writing through the link path", async () => { + // realpath resolves the referent, so a link whose target is missing reports + // ENOENT. Falling back to the link path would replace the symlink with a + // regular file, so the error must propagate and nothing may be committed. + const linkPath = "/tmp/test-dir/dangling-link.txt" + vi.mocked(fs.realpath).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" })) + const linkStats = Object.create(fsSync.Stats.prototype) as fsSync.Stats + linkStats.isSymbolicLink = () => true + vi.mocked(fs.lstat).mockResolvedValue(linkStats) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await expect(safeWriteText(linkPath, "data", { platform: "linux" })).rejects.toThrow("ENOENT") + + expect(fs.rename).not.toHaveBeenCalled() + }) + }) + + // ── Test 8: review fixes (permissions, partial writes, resolution, durability) ── + + describe("review fixes", () => { + it("preserves the target's restrictive mode and tolerates a failed staging-dir permission repair", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o600)) + // a pre-existing staging dir may fail its best-effort permission repair + vi.mocked(fsSync.chmodSync).mockImplementationOnce(() => { + throw new Error("EACCES") + }) + + await safeWriteText(targetPath, "secret", { platform: "linux" }) + + // the staging file inherits the target's 0o600 mode and the write commits + expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), "w", 0o600) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + }) + + it("falls back to the 0o644 default when the target does not exist yet", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + vi.mocked(fsSync.statSync).mockImplementation(() => { + throw Object.assign(new Error("ENOENT"), { code: "ENOENT" }) + }) + + await safeWriteText(targetPath, "fresh", { platform: "linux" }) + + expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), "w", 0o644) + }) + + it("loops on short writes until the full content is durable before fsync", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const content = "0123456789" // 10 bytes + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const buffer = Buffer.from(content, "utf8") + // first write (offset 0) reports 4 bytes (short write); the loop continues + vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) => + args[2] === 0 ? 4 : typeof args[3] === "number" ? args[3] : 0, + ) + + await safeWriteText(targetPath, content, { platform: "linux" }) + + // [0,10) reports 4 bytes, then [4,10) writes the remaining 6 + expect(fsSync.writeSync).toHaveBeenCalledTimes(2) + expect(fsSync.writeSync).toHaveBeenNthCalledWith(1, 1, buffer, 0, 10) + expect(fsSync.writeSync).toHaveBeenNthCalledWith(2, 1, buffer, 4, 6) + expect(fsSync.fsyncSync).toHaveBeenCalledWith(1) + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + }) + + it("stops instead of looping when a write makes no progress at all", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const content = "abcdefg" // 7 bytes + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // Every write reports zero bytes. The short-write loop is bounded by + // offset < buffer.length only, so a zero return would spin on the same + // offset forever, holding the fd and the event loop. + vi.mocked(fsSync.writeSync).mockReturnValue(0) + + const error = await safeWriteText(targetPath, content, { + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(Error) + expect((error as Error).message).toContain("stalled after 0 of 7 bytes") + // The stalled staging file never reached durability or the commit. + expect(fsSync.fsyncSync).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + // The finally around the write closes the descriptor, so a stalled write + // strands neither the fd nor the process. + expect(fsSync.closeSync).toHaveBeenCalledWith(1) + }) + + it("fsyncs the parent directory after the commit rename on POSIX", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + // temp fd=1 then parent-dir fd=2 - distinct fds prove the ordering + vi.mocked(fsSync.openSync).mockReturnValueOnce(1).mockReturnValue(2) + + await safeWriteText(targetPath, "data", { platform: "linux" }) + + // the directory fsync (fd 2) happens only after the file fsync (fd 1); + // the dir path assertion is path-agnostic (stringContaining) because + // path.dirname renders the same input differently on Windows + expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("test-dir"), "r") + expect(fsSync.fsyncSync).toHaveBeenNthCalledWith(1, 1) + expect(fsSync.fsyncSync).toHaveBeenNthCalledWith(2, 2) + expect(fsSync.closeSync).toHaveBeenCalledWith(2) + }) + + it("reports a failed parent-directory fsync instead of claiming a durable write", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync) + .mockReturnValueOnce(1) + .mockImplementationOnce(() => { + throw new Error("EBADF") + }) + + // The content rename committed, so the caller can still find the data at + // the target; what the write cannot claim is that the directory entry + // reached the disk. Returning success here would claim durability the + // filesystem did not grant. + await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toThrow( + PostCommitDurabilityError, + ) + + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath) + }) + + it("propagates realpath errors (EACCES and code-less) instead of the fallback path", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + vi.mocked(fs.realpath).mockRejectedValueOnce(eacces) + await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(eacces) + expect(fs.rename).not.toHaveBeenCalled() + + const plain = new Error("resolution failed") + vi.mocked(fs.realpath).mockRejectedValueOnce(plain) + await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(plain) + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("backup:true propagates access errors (EACCES and code-less) instead of skipping the backup", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const eacces = Object.assign(new Error("EACCES"), { code: "EACCES" }) + const plain = new Error("access failed") + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // each write accesses dirPath then target; only the target access rejects + const rejectTarget = (error: Error) => async (p: unknown) => { + if (typeof p === "string" && p.endsWith("target.txt")) throw error + } + vi.mocked(fs.access) + .mockImplementationOnce(rejectTarget(eacces)) + .mockImplementationOnce(rejectTarget(eacces)) + .mockImplementationOnce(rejectTarget(plain)) + .mockImplementationOnce(rejectTarget(plain)) + + await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toEqual( + expect.objectContaining({ code: "EACCES" }), + ) + await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toThrow( + "access failed", + ) + expect(fs.rename).not.toHaveBeenCalled() + }) + }) + + it("a failed post-commit directory fsync never unlinks the committed target", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const dirPath = path.dirname(targetPath) + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockImplementation((target) => { + if (String(target) === dirPath) throw new Error("EBADF") + return 1 + }) + + await expect(safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })).rejects.toThrow( + PostCommitDurabilityError, + ) + + // The commit state is what cleanup is allowed to act on: the staging file may be + // unlinked only while it is still the staging file. Once the rename has committed, + // the only path this write owns at the target is the published content itself, and + // removing it would turn a durability warning into data loss. + expect(fs.unlink).not.toHaveBeenCalledWith(targetPath) + }) + + it("a failed post-commit directory fsync does not unlink the staging path this write no longer owns", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const dirPath = path.dirname(targetPath) + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + // A caller-supplied staging file: the name is the caller's, not one this write made + // up, so after the commit it is a path another writer may already be using again. + // The caller's staging file sits beside the target, as this contract requires. + const suppliedTemp = path.join(dirPath, "caller.new_data.json") + vi.mocked(fsSync.openSync).mockImplementation((target) => { + if (String(target) === dirPath) throw new Error("EBADF") + return 1 + }) + + await expect( + safeWriteText(targetPath, "new data", { backup: true, platform: "linux", tempPath: suppliedTemp }), + ).rejects.toThrow(PostCommitDurabilityError) + + // The rename consumed the staging file; the commit is what says so. Unlinking the + // staging NAME afterwards is an unlink of whatever now answers to that name. + expect(fs.unlink).not.toHaveBeenCalledWith(suppliedTemp) + expect(fs.unlink).not.toHaveBeenCalledWith(targetPath) + }) + + describe("content bytes", () => { + const targetPath = "/tmp/enc-dir/target.txt" + + beforeEach(() => { + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + }) + + it("stages UTF-8 bytes for string content", async () => { + await safeWriteText(targetPath, "héllo", { platform: "linux" }) + expect(fsSync.writeSync).toHaveBeenCalledWith(1, Buffer.from("héllo", "utf8"), 0, 6) + }) + + it("publishes caller-supplied bytes unchanged instead of re-encoding them", async () => { + // The extension host encodes a document with VS Code's own codec, which + // covers the legacy code pages and BOMs Node cannot represent, and hands + // the result over: those bytes must reach the commit rename exactly as + // they were given. + const bytes = Buffer.from([0x00, 0x68, 0x00, 0x69]) + await safeWriteText(targetPath, bytes, { platform: "linux" }) + expect(fsSync.writeSync).toHaveBeenCalledWith(1, bytes, 0, 4) + }) + }) + it("a no-replace commit links the staged file into place when the target is absent", async () => { + // Isolate the commit-phase counters from any async cleanup a previous + // test left in flight. + vi.mocked(fs.rename).mockClear() + vi.mocked(fs.unlink).mockClear() + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + + await safeWriteText(targetPath, "new data", { failIfExist: true, platform: "linux" }) + + // link(2) is the only atomic no-replace publish: a rename would displace a + // target that appeared after the caller's absence check. + expect(fs.link).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath) + expect(fs.rename).not.toHaveBeenCalled() + // The staged copy is dropped once the name points at it. + expect( + vi.mocked(fs.unlink).mock.calls.some(function (call) { + return String(call[0]).includes("safeWriteText") + }), + ).toBe(true) + }) + + it("a no-replace commit refuses a target that appeared after the caller checked", async () => { + // Isolate the commit-phase counters from any async cleanup a previous + // test left in flight. + vi.mocked(fs.rename).mockClear() + vi.mocked(fs.unlink).mockClear() + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.link).mockRejectedValue(Object.assign(new Error("EEXIST"), { code: "EEXIST" })) + // The failure path still cleans up its staging file and directory; keep those + // promises real so the cleanup does not mask the rejection under test. + vi.mocked(fs.unlink).mockResolvedValue(undefined) + vi.mocked(fs.rmdir).mockResolvedValue(undefined) + + const error = await safeWriteText(targetPath, "new data", { + failIfExist: true, + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(TargetExistsError) + expect((error as TargetExistsError).targetPath).toBe(targetPath) + // Nothing replaced the newer file, and the staged copy is not left behind. + expect(fs.rename).not.toHaveBeenCalled() + expect( + vi.mocked(fs.unlink).mock.calls.some(function (call) { + return String(call[0]).includes("safeWriteText") + }), + ).toBe(true) + }) + + it("resolves an absent target through a symlinked ancestor to the canonical path", async () => { + // The guard pins the publish to the canonical nearest-ancestor path. An absent + // target has to resolve to that same path, or a create through a symlinked + // ancestor aborts with TargetMovedError although nothing moved. + const linkDir = path.resolve("/tmp/link-dir") + const canonicalDir = path.resolve("/real/dir") + const canonical = path.join(canonicalDir, "target.txt") + vi.mocked(fs.realpath).mockImplementation(async (p: unknown) => { + if (String(p) === path.join(linkDir, "target.txt")) { + throw Object.assign(new Error("ENOENT"), { code: "ENOENT" }) + } + if (String(p) === linkDir) return canonicalDir + return String(p) + }) + vi.mocked(fs.lstat).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" })) + + await safeWriteText(path.join(linkDir, "target.txt"), "new data", { + expectedResolvedPath: canonical, + platform: "linux", + }) + + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), canonical) + }) + + it("fails closed when the filesystem has no atomic no-replace primitive", async () => { + // FAT32/exFAT and some SMB mounts reject link(2). Publishing by an exclusive + // copy would put bytes at the final name that readers can observe mid-copy, + // and a crash or an EIO mid-copy leaves damaged bytes there with the + // 'already exists' verdict on retry. No atomic no-replace primitive exists + // on those volumes, so the guarded create refuses to publish at all. + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.link).mockRejectedValue(Object.assign(new Error("ENOTSUP"), { code: "ENOTSUP" })) + + await expect( + safeWriteText(targetPath, "new data", { failIfExist: true, platform: "linux" }), + ).rejects.toBeInstanceOf(UnsupportedFilesystemError) + + // Nothing was published: no copy at the final name, no rename - the name + // stays absent for a retry on a capable volume. + // Every "no hard links here" code takes the same fail-closed path. + for (const code of ["EPERM", "ENOTSUP", "ENOSYS"]) { + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.link).mockRejectedValue(Object.assign(new Error(code), { code })) + + await expect( + safeWriteText(targetPath, "new data", { failIfExist: true, platform: "linux" }), + ).rejects.toBeInstanceOf(UnsupportedFilesystemError) + } + expect(fs.copyFile).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + // Every code reached the link path (the first call plus the three codes + // below), so the loop above really exercised all four refusals. + expect(fs.link).toHaveBeenCalledTimes(4) + // The refusal must not leave its staging file or directory beside the + // target: a regression here would drop a .file-safety-staging_* directory + // on FAT32/exFAT/SMB volumes after every refused create. + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + const stagedDirs = vi.mocked(fsSync.mkdirSync).mock.calls.map((call) => String(call[0])) + expect(vi.mocked(fs.rmdir).mock.calls.map((call) => String(call[0]))).toEqual(stagedDirs) + }) + it("still reports success when the staged copy cannot be unlinked after the link", async () => { + // An antivirus handle on Windows can make unlink fail with EBUSY after link(2) + // published the name. The content is readable at the target, so the write must + // not be reported as a failure the model then retries into an 'already exists'. + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.unlink).mockRejectedValue(Object.assign(new Error("EBUSY"), { code: "EBUSY" })) + + await expect( + safeWriteText(targetPath, "new data", { failIfExist: true, platform: "linux" }), + ).resolves.toBeUndefined() + expect(fs.link).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath) + }) + + it("refuses to publish when the path no longer resolves to the authorized target", async () => { + // Isolate the commit-phase counters from any async cleanup a previous test left + // in flight. + vi.mocked(fs.rename).mockClear() + vi.mocked(fs.link).mockClear() + const authorized = "/tmp/test-dir/target.txt" + // The caller authorized this path while it was a real file in the workspace; by the + // time the publish resolves it, a local process has swapped in a link to somewhere + // else. The decision was never made about that other file, so nothing is published. + vi.mocked(fs.realpath).mockResolvedValue("/outside/the-victim.txt") + + const error = await safeWriteText(authorized, "new data", { + expectedResolvedPath: authorized, + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(TargetMovedError) + const moved = error as TargetMovedError + expect(moved.authorizedPath).toBe(authorized) + expect(moved.resolvedPath).toBe("/outside/the-victim.txt") + expect(moved.message).toContain("/outside/the-victim.txt") + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + // Nothing was staged either: the check runs before the staging directory is made. + expect(fs.mkdir).not.toHaveBeenCalled() + }) + + it("refuses to publish when an authorized parent directory was replaced after the check", async () => { + // expectedResolvedPath pins the NAME being published, so it cannot notice the + // directory the name lives in being swapped for another one (a link to outside the + // workspace looks exactly like this). The recorded ancestor identities are what + // catch it, and the commit is aborted before anything is moved into place. + const dir = path.resolve("/tmp/test-dir") + const targetPath = path.join(dir, "target.txt") + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.rename).mockClear() + vi.mocked(fs.link).mockClear() + vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(999n)) // was 100n when authorized + + const error = await safeWriteText(targetPath, "new data", { + expectedResolvedPath: targetPath, + expectedAncestorIdentities: [{ dir, dev: 1n, ino: 100n }], + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(AncestorReplacedError) + expect((error as AncestorReplacedError).directory).toBe(dir) + expect((error as AncestorReplacedError).message).toContain("no longer the directory that was authorized") + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + // The staged copy is cleaned up rather than left beside the target. + expect(vi.mocked(fs.unlink).mock.calls.some((call) => String(call[0]).includes("safeWriteText"))).toBe(true) + }) + + it("refuses to publish when an authorized ancestor name was moved and replaced by a link", async () => { + // Moving a directory preserves (dev, ino), and replacing the old name with a + // symlink to the moved location keeps the identity check matching - stat + // follows the link. The commit takes path strings and would follow it too, + // publishing at the moved location outside the chain the caller walked, so + // the authorized name must still RESOLVE to the authorized location. + const dir = path.resolve("/tmp/test-dir") + const movedDir = path.resolve("/outside/workspace") + const targetPath = path.join(dir, "target.txt") + vi.mocked(fs.realpath).mockImplementation(async (p) => + path.resolve(String(p)) === dir ? movedDir : targetPath, + ) + vi.mocked(fs.rename).mockClear() + vi.mocked(fs.link).mockClear() + vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(100n)) // SAME identity as authorized + + const error = await safeWriteText(targetPath, "new data", { + expectedResolvedPath: targetPath, + expectedAncestorIdentities: [{ dir, dev: 1n, ino: 100n }], + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(AncestorReplacedError) + expect((error as AncestorReplacedError).message).toContain("no longer resolves to the authorized location") + // Nothing was published at either location. + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) + + it("propagates a transient realpath failure instead of reporting a replaced ancestor", async () => { + // EACCES/EIO while re-validating the authorized ancestry is not a containment + // violation: reporting AncestorReplacedError would point the user (and the + // model) at a security problem that is not there. + const dir = path.resolve("/tmp/test-dir") + const targetPath = path.join(dir, "target.txt") + const denied = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + vi.mocked(fs.realpath).mockImplementation(async (p) => { + if (path.resolve(String(p)) === dir) throw denied + return targetPath + }) + vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(100n)) + + const error = await safeWriteText(targetPath, "new data", { + expectedResolvedPath: targetPath, + expectedAncestorIdentities: [{ dir, dev: 1n, ino: 100n }], + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBe(denied) + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) + + it("publishes when the recorded ancestor identities are unchanged", async () => { + // The pin must not turn every guarded write into a false rejection: an unchanged + // directory chain publishes normally. + const dir = path.resolve("/tmp/test-dir") + const targetPath = path.join(dir, "target.txt") + // The unchanged chain resolves where it names: the ancestor realpath check + // sees the authorized directory itself, not a moved location. + vi.mocked(fs.realpath).mockImplementation(async (p) => (path.resolve(String(p)) === dir ? dir : targetPath)) + vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(100n)) + + await safeWriteText(targetPath, "new data", { + expectedResolvedPath: targetPath, + expectedAncestorIdentities: [{ dir, dev: 1n, ino: 100n }], + platform: "linux", + }) + + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath) + }) + + it("publishes when a pinned ancestor is a stable symlink alias", async () => { + // A caller that authorized a chain running THROUGH an alias records the alias spelling as + // dir and the location that alias resolves to as resolvedPath. The alias's realpath differs + // from dir by definition while nothing moved, so comparing realpath(dir) against dir alone + // refused a write whose ancestry and target never changed. The (dev, ino) check is what + // still catches the alias being re-pointed; this row is the control on that. + const aliasDir = path.resolve("/tmp/alias-dir") + const realDir = path.resolve("/tmp/real-dir") + const targetPath = path.join(aliasDir, "target.txt") + vi.mocked(fs.realpath).mockImplementation(async (p: unknown) => + path.resolve(String(p)) === aliasDir ? realDir : targetPath, + ) + vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(100n)) + vi.mocked(fs.rename).mockClear() + vi.mocked(fs.link).mockClear() + + await safeWriteText(targetPath, "new data", { + expectedResolvedPath: targetPath, + expectedAncestorIdentities: [{ dir: aliasDir, dev: 1n, ino: 100n, resolvedPath: realDir }], + platform: "linux", + }) + + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath) + }) + + it("refuses the publish when a pinned alias no longer resolves to the authorized location", async () => { + // resolvedPath has to stay a comparison, not an escape hatch: an alias re-pointed to a third + // location resolves to neither the location it was authorized against nor its own spelling, + // and the commit must stop there instead of publishing through the new link. + const aliasDir = path.resolve("/tmp/alias-dir") + const authorizedLocation = path.resolve("/tmp/real-dir") + const repointedTo = path.resolve("/tmp/elsewhere-dir") + const targetPath = path.join(aliasDir, "target.txt") + vi.mocked(fs.realpath).mockImplementation(async (p: unknown) => + path.resolve(String(p)) === aliasDir ? repointedTo : targetPath, + ) + vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(100n)) + vi.mocked(fs.rename).mockClear() + vi.mocked(fs.link).mockClear() + + const error = await safeWriteText(targetPath, "new data", { + expectedResolvedPath: targetPath, + expectedAncestorIdentities: [{ dir: aliasDir, dev: 1n, ino: 100n, resolvedPath: authorizedLocation }], + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(AncestorReplacedError) + expect((error as AncestorReplacedError).message).toContain("no longer resolves to the authorized location") + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) + + it("fsyncs every parent directory it had to create, not only the target's immediate parent", async () => { + // The commit rename makes the entry INSIDE the immediate parent durable. A grandparent this + // call created is itself an entry in ITS parent, so syncing only the immediate parent leaves + // the newer ancestors unsynced: a crash can drop the chain and take the published file with + // it. The double reports the two nested components as created, which is what mkdir answers + // on the real filesystem, so the sync order is observable: deepest first, ending with the + // directory that holds the outermost new entry. Only directories are opened with "r", so + // the calls below are directory syncs and nothing else. + const root = path.resolve("/tmp/test-dir") + const nested = path.join(root, "nested") + const deep = path.join(nested, "deep") + const targetPath = path.join(deep, "target.txt") + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + // The outermost component mkdir had to create, in the spelling Node answers with. + vi.mocked(fs.mkdir).mockResolvedValue(nested) + vi.mocked(fsSync.openSync).mockClear() + // Distinct descriptors per directory, so a flush is attributable to the directory it belongs + // to rather than being one indistinguishable call on an undefined handle. + const dirDescriptors: Record = { [deep]: 901, [nested]: 902, [root]: 903 } + vi.mocked(fsSync.openSync).mockImplementation(function (p: unknown) { + return dirDescriptors[path.resolve(String(p))] ?? 1 + }) + + await safeWriteText(targetPath, "new data", { platform: "linux" }) + + const dirSyncs = vi + .mocked(fsSync.openSync) + .mock.calls.filter(function (call: unknown[]) { + return call[1] === "r" + }) + .map(function (call: unknown[]) { + return String(call[0]) + }) + expect(dirSyncs).toEqual([deep, nested, root]) + // The open list alone only proves handles were taken. The durable effect is the flush: a + // production change that opened each created ancestor and closed it without fsyncing would leave + // this row green while the chain it just created stayed volatile, so each descriptor the open + // list names is pinned to its own flush and its own close, in the same deepest-first order. + const dirFdSet = new Set([901, 902, 903]) + const dirFlushes = vi + .mocked(fsSync.fsyncSync) + .mock.calls.filter(function (call: unknown[]) { + return dirFdSet.has(call[0] as number) + }) + .map(function (call: unknown[]) { + return call[0] + }) + expect(dirFlushes).toEqual([901, 902, 903]) + const dirCloses = vi + .mocked(fsSync.closeSync) + .mock.calls.filter(function (call: unknown[]) { + return dirFdSet.has(call[0] as number) + }) + .map(function (call: unknown[]) { + return call[0] + }) + expect(dirCloses).toEqual([901, 902, 903]) + }) + + // A row about what the Windows filesystem reports, so it belongs to the Windows leg: it is + // gated exactly like the icacls rows in this describe. The marker is stripped by a string + // comparison, but deciding WHICH directories the answer names walks the runner's own path + // semantics, and on POSIX a drive-lettered path like "C:/test-dir/nested" is not even + // absolute, so a marker built that way is an input the platform cannot produce. The option + // keeps the write on the non-win32 durability branch - the branch this row is about - while + // the runner supplies win32 path semantics. The POSIX spelling of the same answer is pinned + // by the preceding row, and the answer this write cannot place by the row after it. + it.skipIf(process.platform !== "win32")( + "maps the namespace marker Windows reports for the directory it created", + async () => { + const nested = path.resolve("C:/test-dir/nested") + const deep = path.join(nested, "deep") + const targetPath = path.join(deep, "target.txt") + const stripped = nested.startsWith("/") ? nested.slice(1) : nested + const reported = "\\\\?\\" + stripped.split("/").join("\\") + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.mkdir).mockResolvedValue(reported) + vi.mocked(fsSync.openSync).mockClear() + + await safeWriteText(targetPath, "new data", { platform: "linux" }) + + const dirSyncs = vi + .mocked(fsSync.openSync) + .mock.calls.filter(function (call: unknown[]) { + return call[1] === "r" + }) + .map(function (call: unknown[]) { + return String(call[0]) + }) + // The marker had to map onto the write's own paths: nothing under the marker is synced. + expect(dirSyncs).toEqual([deep, nested, path.dirname(nested)]) + expect( + dirSyncs.some(function (p: string) { + return p.includes("?") + }), + ).toBe(false) + }, + ) + + it("syncs no ancestor when mkdir names a directory this write cannot place", async () => { + // The chain is derived by walking up from the target's own directory until it reaches what + // mkdir reported. An answer that is not on that walk is not a directory this write created, + // and it must not be synced: flushing a directory someone else owns, while the published + // file's own new ancestors stay unsynced, is the opposite of what step 4b is for. Only the + // immediate parent is flushed, because the commit rename put its entry there. Constructed + // from path.resolve so the answer is absolute, and off the walk, on both platforms. + const targetPath = path.join(path.resolve("/tmp/test-dir/deep"), "target.txt") + const unrelated = path.resolve("/tmp/other-tree/nested") + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.mkdir).mockResolvedValue(unrelated) + vi.mocked(fsSync.openSync).mockClear() + + await safeWriteText(targetPath, "new data", { platform: "linux" }) + + const dirSyncs = vi + .mocked(fsSync.openSync) + .mock.calls.filter(function (call: unknown[]) { + return call[1] === "r" + }) + .map(function (call: unknown[]) { + return String(call[0]) + }) + expect(dirSyncs).toEqual([path.dirname(targetPath)]) + expect( + dirSyncs.some(function (p: string) { + return p.includes(unrelated) + }), + ).toBe(false) + }) + + it("reports a post-commit durability failure together with the backup it cannot remove", async () => { + // The commit rename succeeded and then the parent-directory fsync failed. Nothing is rolled + // back - the published bytes stay at the target - and the failure path still removes the + // backup. When that removal also fails the caller gets both facts: contentPublished says the + // leftover is stale beside published content, and originalError names the durability failure. + const targetPath = "/tmp/test-dir/target.txt" + const eio = Object.assign(new Error("EIO"), { code: "EIO" }) + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + // Only directories are opened with "r", so this fd marks the post-commit directory sync: + // the failure lands exactly after the rename instead of on the staged file's fsync. + vi.mocked(fsSync.openSync).mockImplementation(function (p: unknown, flags?: unknown): number { + return flags === "r" ? 77 : 1 + }) + vi.mocked(fsSync.fsyncSync).mockImplementation(function (fd: number): void { + if (fd === 77) { + throw eio + } + }) + vi.mocked(fs.unlink).mockImplementation(async (p: unknown) => { + if (String(p).includes("safeWriteText.bak_")) { + throw Object.assign(new Error("EPERM"), { code: "EPERM" }) + } + }) + vi.mocked(fs.rename).mockClear() + + const error = await safeWriteText(targetPath, "new data", { + backup: true, + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(OrphanedBackupAfterFailedWriteError) + const orphan = error as OrphanedBackupAfterFailedWriteError + // The commit ran: the durability failure is downstream of the rename, not before it. + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath) + expect(orphan.contentPublished).toBe(true) + expect(orphan.originalError).toBeInstanceOf(PostCommitDurabilityError) + expect((orphan.cleanupError as Error).message).toBe("EPERM") + expect(orphan.message).toContain("the target holds the new content") + // Both removal attempts ran, and the failure path still cleaned what it owned. + const backupUnlinks = vi.mocked(fs.unlink).mock.calls.filter(function (call: unknown[]) { + return typeof call[0] === "string" && call[0].includes("safeWriteText.bak_") + }) + expect(backupUnlinks).toHaveLength(2) + expect(fs.rmdir).toHaveBeenCalled() + }) + + it("refuses the publish when an authorized ancestor disappears before the commit", async () => { + const dir = path.resolve("/tmp/test-dir") + const targetPath = path.join(dir, "target.txt") + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.stat).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" })) + + const error = await safeWriteText(targetPath, "new data", { + expectedResolvedPath: targetPath, + expectedAncestorIdentities: [{ dir, dev: 1n, ino: 100n }], + platform: "linux", + }).catch((caught: unknown) => caught) + + expect(error).toBeInstanceOf(AncestorReplacedError) + expect((error as AncestorReplacedError).message).toContain("no longer exists") + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) +}) + +// ── Test 12: lock key, staging path, and post-commit durability ───────────── + +describe("resolveLockKey", () => { + beforeEach(() => mockDefaults()) + + it("canonicalizes the parent directory, not just the file", async () => { + vi.mocked(fs.realpath).mockImplementation(async (target) => { + const key = String(target) + if (key === "/tmp/linkdir/file.json") return "/real/dir/file.json" + if (key === "/real/dir") return "/real/dir" + return key + }) + + // The key is the canonical directory plus the basename, so a symlinked + // ancestor and its referent share one lock. + await expect(resolveLockKey("/tmp/linkdir/file.json")).resolves.toBe(path.join("/real/dir", "file.json")) + }) + + it("computes a key for a dangling link, which resolvePublishTarget refuses", async () => { + const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fs.realpath).mockRejectedValue(enoent) + vi.mocked(fs.lstat).mockResolvedValue(_fileStats(true)) + // The walk ends when readlink throws, because a plain file is not a link. + // Answering every call with the same value would let a walk that never + // stopped return the same key, so the mock has to distinguish the link from + // the referent and the test has to check that the walk stopped. + const notALink = Object.assign(new Error("EINVAL: not a link"), { code: "EINVAL" }) + vi.mocked(fs.readlink).mockImplementation(async (target) => { + if (String(target) === "/tmp/linkdir/file.json") return "referent.json" + throw notALink + }) + + // Mid-commit a peer writer renames the referent away and back, so the key + // must still be computable while the link dangles. + await expect(resolveLockKey("/tmp/linkdir/file.json")).resolves.toBe( + path.resolve(path.join("/tmp/linkdir", "referent.json")), + ) + // Two calls means the walk stopped at the referent: the link, then one more + // on the referent that reports it is not a link. A walk that never stopped + // would run the full 8 steps. + expect(fs.readlink).toHaveBeenCalledTimes(2) + }) + + it("terminates on a two-link cycle instead of walking forever", async () => { + const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fs.realpath).mockRejectedValue(enoent) + vi.mocked(fs.lstat).mockResolvedValue(_fileStats(true)) + // Every readlink answers with the same link, so an unbounded walk would + // never end; the bounded walk returns the key it actually reached. + vi.mocked(fs.readlink).mockImplementation(async () => "a.json") + + await expect(resolveLockKey("/tmp/linkdir/a.json")).resolves.toBe( + path.resolve(path.join("/tmp/linkdir", "a.json")), + ) + expect(fs.readlink).toHaveBeenCalledTimes(8) + }) +}) + +describe("caller-supplied staging path", () => { + beforeEach(() => mockDefaults()) + + it("rejects a staging file outside the target's directory before writing anything", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + + // A rename across filesystems fails with EXDEV, and a path elsewhere lets + // a caller publish an unrelated file onto the target. + await expect( + safeWriteText(targetPath, "data", { tempPath: "/tmp/other-dir/x.tmp", platform: "linux" }), + ).rejects.toThrow(StagingPathError) + expect(fsSync.openSync).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("rejects a staging path that is a symlink", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fs.lstat).mockResolvedValue(_fileStats(true)) + + // Renaming a link over the target publishes whatever the link points at. + await expect( + safeWriteText(targetPath, "data", { tempPath: "/tmp/test-dir/x.tmp", platform: "linux" }), + ).rejects.toThrow(StagingPathError) + expect(fsSync.openSync).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("rejects a staging path that is the target itself", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + // Same inode and device for the supplied staging path and the target: the + // failure handler would unlink the only copy of the content, so a failed + // write would delete the file it was meant to protect. + const stats = _fileIdentity(42n, 7n) + vi.mocked(fs.lstat).mockResolvedValue(stats) + + await expect(safeWriteText(targetPath, "data", { tempPath: targetPath, platform: "linux" })).rejects.toThrow( + StagingPathError, + ) + expect(fsSync.openSync).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + // The comparison is only sound when both stats are read as bigint: on NTFS/ReFS the file + // identifiers exceed Number.MAX_SAFE_INTEGER. + // Filter on the options, not the spelling: path.resolve prefixes a drive letter on Windows, + // so the two identity reads are the calls that asked for options at all. + const identityLookups = vi.mocked(fs.lstat).mock.calls.filter((c) => c[1] !== undefined) + expect(identityLookups.length).toBeGreaterThanOrEqual(2) + for (const c of identityLookups) { + expect(c[1]).toEqual({ bigint: true }) + } + expect(fs.unlink).not.toHaveBeenCalled() + }) + + it("rejects when the target identity cannot be compared for a reason other than a missing target", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + // A hard-linked staging file shares the target's inode, so the identity comparison is the only thing + // between this write and a rename onto the very file the guard protects. An EACCES from the target + // lstat must not be mistaken for "there is no target". + const stagingStats = _fileIdentity(42n, 7n) + vi.mocked(fs.lstat).mockImplementation(async (p) => { + if (String(p) === targetPath) { + throw Object.assign(new Error("EACCES"), { code: "EACCES" }) + } + return stagingStats + }) + + await expect( + safeWriteText(targetPath, "data", { tempPath: "/tmp/test-dir/hardlink.txt", platform: "linux" }), + ).rejects.toThrow("Staging file could not be compared with the target") + expect(fsSync.openSync).not.toHaveBeenCalled() + expect(fs.rename).not.toHaveBeenCalled() + // Both identity reads must ask for bigint stats, or the comparison silently falls + // back to rounded numbers on NTFS/ReFS. + const identityLookups = vi.mocked(fs.lstat).mock.calls.filter((c) => c[1] !== undefined) + expect(identityLookups).toHaveLength(2) + for (const c of identityLookups) { + expect(c[1]).toEqual({ bigint: true }) + } + }) +}) + +describe("cleanup before a rollback failure is reported", () => { + beforeEach(() => mockDefaults()) + + it("releases the staged file, its copy and its own staging directory before throwing", async () => { + const targetPath = "/tmp/test-dir/target.txt" + vi.mocked(fs.realpath).mockResolvedValue(targetPath) + vi.mocked(fsSync.openSync).mockReturnValue(1) + // The commit rename is the only rename in this flow and it fails. + vi.mocked(fs.rename).mockRejectedValue(new Error("ENOSPC")) + + await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toThrow("ENOSPC") + + // The staging file and this write's own directory must not leak, and neither may + // the backup copy: the target still holds the pre-write content on disk. + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_")) + const stagingDirs = vi.mocked(fsSync.mkdirSync).mock.calls.map((call) => String(call[0])) + expect(stagingDirs.length).toBe(1) + expect(fs.rmdir).toHaveBeenCalledWith(stagingDirs[0]) + + const failingRenameOrder = vi.mocked(fs.rename).mock.invocationCallOrder[0] + const unlinkOrder = vi.mocked(fs.unlink).mock.invocationCallOrder[0] + const rmdirOrder = vi.mocked(fs.rmdir).mock.invocationCallOrder[0] + expect(unlinkOrder).toBeGreaterThan(failingRenameOrder) + expect(rmdirOrder).toBeGreaterThan(failingRenameOrder) + }) +}) + +describe("resolvePublishTarget", () => { + beforeEach(() => mockDefaults()) + + it("propagates an lstat failure that is not ENOENT instead of falling back to the link path", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + vi.mocked(fs.realpath).mockRejectedValue(enoent) + vi.mocked(fs.lstat).mockRejectedValue(eacces) + + // A failed lstat says nothing about whether the path is a link, so the + // fallback would publish through a link we were not allowed to inspect. + await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(eacces) + expect(fs.rename).not.toHaveBeenCalled() + }) + + it("still falls back to the given path when lstat also reports the path as absent", async () => { + const targetPath = "/tmp/test-dir/target.txt" + const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fs.realpath).mockRejectedValue(enoent) + vi.mocked(fs.lstat).mockRejectedValue(enoent) + vi.mocked(fsSync.openSync).mockReturnValue(1) + + await safeWriteText(targetPath, "data", { platform: "linux" }) + + // The fallback is the resolved path, not the string that was handed in. + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), path.resolve(targetPath)) + }) +}) + +describe("resolveLockKey when the parent directory does not exist yet", () => { + beforeEach(() => mockDefaults()) + + it("canonicalizes through the nearest existing ancestor instead of the literal parent", async () => { + // Two writers must take ONE lock: the one whose parent directory is already there, + // and the one racing to create it. Resolving only the immediate parent and falling + // back to its literal spelling on ENOENT gave them different keys whenever an + // ancestor was a symlink or a Windows short name, so a read-modify-write under the + // advisory lock lost one side. + const aliasDir = path.resolve("/tmp/alias-parent") + const canonicalDir = path.resolve("/tmp/real-parent") + const nested = path.join(aliasDir, "nested") + const target = path.join(nested, "history_item.json") + vi.mocked(fs.lstat).mockResolvedValue(_fileStats(false)) + vi.mocked(fs.realpath).mockImplementation(async (p) => { + const s = String(p) + if (s === target || s === nested) { + throw Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + } + if (s === aliasDir) { + return canonicalDir + } + return s + }) + + expect(await resolveLockKey(target)).toBe(path.join(canonicalDir, "nested", "history_item.json")) + }) + + it("propagates a realpath failure that is not ENOENT instead of guessing a key", async () => { + // A realpath that fails for another reason says nothing about the canonical form; + // returning a literal key would silently put this writer on a different lock. + const target = path.join(path.resolve("/tmp/test-dir"), "history_item.json") + vi.mocked(fs.lstat).mockResolvedValue(_fileStats(false)) + // Not a link: the walk must reach the canonicalization step, which is where the + // non-ENOENT failure has to surface. + vi.mocked(fs.readlink).mockRejectedValue( + Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }), + ) + vi.mocked(fs.realpath).mockImplementation(async (p) => { + if (String(p) === target) return target + throw Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + }) + + await expect(resolveLockKey(target)).rejects.toThrow("EACCES") + }) +}) + +// -- asks landed at the refreshed 2357 footing -------------------------------- +// +// Rows for the review asks on this file's own footing. Each row needs the line it describes: +// the round's negative control makes that line inert and these are the rows that fail. + +describe("asks landed at the refreshed 2357 footing", () => { + beforeEach(() => { + mockDefaults() + vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) => + typeof args[3] === "number" ? args[3] : 0, + ) + }) + describe("created directories validated against the authorized location", () => { + // The created chain is sampled AFTER the mkdir, so it records where the created directory ended + // up, not where the caller authorized it to be. A directory that was not there when the caller + // authorized can be a link by the time mkdir reaches it, and the created parent then sits + // outside the chain the caller walked. + function _scenario(linkPlantedDuringMkdir: boolean) { + const pinned = path.resolve("/ws/a") + const created = path.join(pinned, "new") + const escaped = path.resolve("/outside/new") + const target = path.join(created, "target.txt") + let linkPlanted = false + const enoent = () => Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fs.realpath).mockImplementation(async (p) => { + const s = String(p) + if (s === target || (s === created && !linkPlanted)) throw enoent() + // The link is planted between the canonicalization and the mkdir answer, so the same name + // resolves elsewhere by the time the created chain is used. + return s === created ? escaped : s + }) + // Node reports the outermost directory mkdir created, in the caller's spelling. + vi.mocked(fs.mkdir).mockImplementation(async () => { + linkPlanted = linkPlantedDuringMkdir + return created + }) + vi.mocked(fsSync.openSync).mockReturnValue(1) + return { pinned, created, target } + } + const pin = (dir: string) => [{ dir, dev: 1n, ino: 100n, resolvedPath: dir }] + it("refuses to publish when the directory mkdir created resolves outside the location the caller authorized", async () => { + const { pinned, target } = _scenario(true) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedAncestorIdentities: pin(pinned), + }) + await expect(promise).rejects.toBeInstanceOf(AncestorReplacedError) + // The pin covers the name mkdir reported, so the refusal now lands on the containment + // check that compares the resolved directory against the selected location. + await expect(promise).rejects.toThrow(/outside the authorized location/) + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) + it("publishes when the created directory resolves inside the location the caller authorized", async () => { + const { pinned, target } = _scenario(false) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedAncestorIdentities: pin(pinned), + }) + await expect(promise).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }) + it("leaves the created chain alone when the caller pinned no location", async () => { + const { target } = _scenario(true) + const promise = safeWriteText(target, "data", { platform: "linux" }) + await expect(promise).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }) + it("publishes when a created directory merely has a name that begins with two dots under the pinned location", async () => { + // A directory named ..cache is an ordinary child of the location the caller pinned. The + // containment predicate read every name beginning with two dots as a walk out of the pin, + // so this write was refused with AncestorReplacedError before anything was staged, even + // though the pin the caller handed in covers it by its own name. + const pinned = path.resolve("/ws") + const created = path.join(pinned, "..cache") + const target = path.join(created, "new", "target.txt") + const enoent = () => Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fs.realpath).mockImplementation(async (p) => { + const s = String(p) + if (s === target) throw enoent() + // Nothing on this chain moved: the name carrying two leading dots is the only thing + // that separates this scenario from the one above. + return s + }) + // The outermost directory mkdir created, in the spelling Node answers with. + vi.mocked(fs.mkdir).mockImplementation(async () => created) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedAncestorIdentities: pin(pinned), + }) + await expect(promise).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }) + it("refuses to publish when a created directory resolves under a shallower pin than the name it was created under", async () => { + // Two ancestor pins, /ws and /ws/a. mkdir reports creating /ws/a/new, and the link is + // planted only when mkdir answers, so the name the chain carries is still the one the + // caller walked while the directory it resolves to now sits under the shallower pin. + // A pin selected by the resolved path finds /ws, whose containment check the redirected + // directory passes, so the write publishes through grounds the caller never authorized + // for that name. + const shallow = path.resolve("/ws") + const deep = path.resolve("/ws/a") + const created = path.join(deep, "new") + const redirected = path.join(shallow, "other", "new") + const target = path.join(created, "target.txt") + let linkPlanted = false + const enoent = () => Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fs.realpath).mockImplementation(async (p) => { + const s = String(p) + if (s === target || (s === created && !linkPlanted)) throw enoent() + return s === created ? redirected : s + }) + vi.mocked(fs.mkdir).mockImplementation(async () => { + linkPlanted = true + return created + }) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedAncestorIdentities: [ + { dir: shallow, dev: 1n, ino: 100n, resolvedPath: shallow }, + { dir: deep, dev: 1n, ino: 100n, resolvedPath: deep }, + ], + }) + await expect(promise).rejects.toBeInstanceOf(AncestorReplacedError) + await expect(promise).rejects.toThrow(/outside the authorized location/) + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) + it("publishes when the created chain sits under the location a pinned alias resolved to", async () => { + // The control on selecting by name. A caller that authorized a chain THROUGH an alias + // records the alias spelling as dir and the location that alias resolves to as + // resolvedPath, and mkdir answers on the location side. Selecting by dir alone would find + // no pin for this chain and refuse a write whose ancestry never moved. + const aliasDir = path.resolve("/ws/alias") + const authorizedLocation = path.resolve("/ws/real") + const created = path.join(authorizedLocation, "new") + const target = path.join(created, "target.txt") + const enoent = () => Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fs.realpath).mockImplementation(async (p) => { + const s = String(p) + if (s === target) throw enoent() + return path.resolve(s) === aliasDir ? authorizedLocation : s + }) + vi.mocked(fs.mkdir).mockImplementation(async () => created) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedAncestorIdentities: [{ dir: aliasDir, dev: 1n, ino: 100n, resolvedPath: authorizedLocation }], + }) + await expect(promise).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }) + it("refuses to publish when a deeper pin covers the created name better than a longer alias spelling does", async () => { + // Two pins cover the name mkdir reported creating. The identity pin reached it + // through an alias, so its dir is the alias spelling /ws/long-root-alias - longer + // than anything on the deeper side - while only the location that alias resolved to, + // /ws, covers the created name at all. The path-form pin names the created directory + // itself. Ranking candidates by the length of their dir field put the longer alias + // first, so the containment check ran against /ws and a created /ws/a/new that had + // become a link into /ws/other passed it, publishing through ground the caller never + // authorized under that name. + const shallow = path.resolve("/ws") + const aliasDir = path.resolve("/ws/long-root-alias") + const created = path.resolve("/ws/a/new") + const redirected = path.join(shallow, "other", "new") + const target = path.join(created, "target.txt") + let linkPlanted = false + const enoent = () => Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + vi.mocked(fs.realpath).mockImplementation(async (p) => { + const s = String(p) + if (s === target || (s === created && !linkPlanted)) throw enoent() + // The alias spelling stands for the location it was recorded resolving to, and the + // created name became a link into shallower grounds between the canonicalization + // and the mkdir answer. + if (path.resolve(s) === aliasDir) return shallow + return s === created ? redirected : s + }) + vi.mocked(fs.mkdir).mockImplementation(async () => { + linkPlanted = true + return created + }) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedAncestorIdentities: [{ dir: aliasDir, dev: 1n, ino: 100n, resolvedPath: shallow }], + expectedResolvedPath: target, + }) + await expect(promise).rejects.toBeInstanceOf(AncestorReplacedError) + await expect(promise).rejects.toThrow(/outside the authorized location/) + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) + }) + describe("target group carried onto the staging descriptor before publication", () => { + // The commit publishes the staging inode, so the group the published file ends up in is whatever + // the staging descriptor carried when it closed. The mode was re-applied with fchmodSync; the + // group was not carried at all. + const GID = 4321 + function _targetWithGroup(target: string, fd: number): void { + vi.mocked(fs.realpath).mockResolvedValue(target) + vi.mocked(fsSync.openSync).mockReturnValue(fd) + // A Stats stand-in that reports a group, the way a POSIX target does. + vi.mocked(fsSync.statSync).mockReturnValue(Object.assign(_stats(0o600), { gid: GID })) + } + it("carries the existing target's group onto the staging descriptor before the commit", async () => { + const target = path.resolve("/ws/b/target.txt") + _targetWithGroup(target, 1) + await safeWriteText(target, "data", { platform: "linux" }) + expect(fsSync.fchmodSync).toHaveBeenCalledWith(1, 0o600) + expect(fsSync.fchownSync).toHaveBeenCalledWith(1, -1, GID) + // Before the close and the rename: after the commit the name belongs to the published file and + // the window to carry anything onto that descriptor is gone. + expect(vi.mocked(fsSync.fchownSync).mock.invocationCallOrder[0]).toBeLessThan( + vi.mocked(fsSync.closeSync).mock.invocationCallOrder[0], + ) + }) + it("carries the group onto a caller-supplied staging descriptor as well", async () => { + const target = path.resolve("/ws/c/target.txt") + const staged = path.join(path.dirname(target), "x.tmp") + _targetWithGroup(target, 7) + await safeWriteText(target, "data", { tempPath: staged, platform: "linux" }) + expect(fsSync.openSync).toHaveBeenCalledWith(staged, "r+") + expect(fsSync.fchmodSync).toHaveBeenCalledWith(7, 0o600) + expect(fsSync.fchownSync).toHaveBeenCalledWith(7, -1, GID) + }) + it("asks for no group when the target is not there yet", async () => { + const target = path.resolve("/ws/b/fresh.txt") + vi.mocked(fs.realpath).mockResolvedValue(target) + vi.mocked(fsSync.openSync).mockReturnValue(1) + vi.mocked(fsSync.statSync).mockImplementation(() => { + throw Object.assign(new Error("ENOENT: no such file or directory, stat"), { code: "ENOENT" }) + }) + await safeWriteText(target, "data", { platform: "linux" }) + expect(fsSync.fchownSync).not.toHaveBeenCalled() + expect(fs.rename).toHaveBeenCalledTimes(1) + }) + }) + describe("cancellation honoured at the commit gate", () => { + // Publish was one awaited submission with nothing a caller could cancel. Every step before the + // commit is awaited, so the commit gate is the last point where publishing can still be refused. + it("publishes nothing when the caller cancels before the commit", async () => { + const target = path.resolve("/ws/d/target.txt") + vi.mocked(fs.realpath).mockResolvedValue(target) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const controller = new AbortController() + controller.abort() + const promise = safeWriteText(target, "data", { platform: "linux", signal: controller.signal }) + await expect(promise).rejects.toBeInstanceOf(PublishCancelledError) + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + // The staged file this write made is removed by the failure cleanup. + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + }) + it("publishes nothing when the caller cancels while the backup copy is in flight", async () => { + const target = path.resolve("/ws/e/target.txt") + vi.mocked(fs.realpath).mockResolvedValue(target) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const controller = new AbortController() + vi.mocked(fs.copyFile).mockImplementation(async () => { + controller.abort() + }) + const promise = safeWriteText(target, "data", { + platform: "linux", + backup: true, + signal: controller.signal, + }) + await expect(promise).rejects.toBeInstanceOf(PublishCancelledError) + expect(fs.rename).not.toHaveBeenCalled() + // Both files this write made go: the staged file and the copy of the previous content. + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak")) + expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_")) + }) + it("commits when the caller hands a signal that never fires", async () => { + const target = path.resolve("/ws/f/target.txt") + vi.mocked(fs.realpath).mockResolvedValue(target) + vi.mocked(fsSync.openSync).mockReturnValue(1) + const controller = new AbortController() + const promise = safeWriteText(target, "data", { platform: "linux", signal: controller.signal }) + await expect(promise).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }) + }) +}) + +describe("created root in the extended-length namespace", () => { + // Node reports the directory mkdir created through the Windows extended-length namespace, and + // only Windows spells a UNC root that way: the marker plus the "UNC" label stands for the + // leading backslash pair. These rows run where that marker can appear and are skipped where it + // cannot, so the spelling the fix answers is tested rather than assumed. + const markerVisibleHere = process.platform === "win32" + const conditionalIt = markerVisibleHere ? it : it.skip + const serverRoot = "\\\\server\\share\\ws" + const created = "\\\\server\\share\\ws\\new" + const target = "\\\\server\\share\\ws\\new\\target.txt" + const escaped = "\\\\outside\\share\\new" + // The answer mkdir gives for a UNC target on Node 22, in the namespace spelling. + const mkdirAnswer = "\\\\?\\UNC\\server\\share\\ws\\new" + function _uncScenario(redirectCreatedDirectory: boolean) { + vi.mocked(fs.realpath).mockImplementation(async (p) => { + const s = String(p) + // The planted redirect makes the created directory resolve under a host nothing pinned. + if (redirectCreatedDirectory && s === created) return escaped + return s + }) + vi.mocked(fs.mkdir).mockResolvedValue(mkdirAnswer) + vi.mocked(fsSync.openSync).mockReturnValue(1) + return [{ dir: serverRoot, dev: 1n, ino: 100n, resolvedPath: serverRoot }] + } + beforeEach(() => { + mockDefaults() + vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) => + typeof args[3] === "number" ? args[3] : 0, + ) + }) + conditionalIt( + "refuses to publish when the created UNC directory resolves under nothing the caller pinned", + async () => { + const pin = _uncScenario(true) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedAncestorIdentities: pin, + }) + await expect(promise).rejects.toBeInstanceOf(AncestorReplacedError) + // Selection is by the name the created chain carries, and the pin covers that name, so the + // refusal lands on the containment check rather than on the absence of any pin. + await expect(promise).rejects.toThrow(/outside the authorized location/) + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }, + ) + conditionalIt( + "publishes when the created UNC directory resolves inside the location the caller pinned", + async () => { + const pin = _uncScenario(false) + await expect( + safeWriteText(target, "data", { platform: "linux", expectedAncestorIdentities: pin }), + ).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }, + ) +}) + +describe("effective parent validated when mkdir created nothing", () => { + // mkdir names no first created directory when the final directory was already there, and a + // name that is a link to a directory answers the same way because the stat after the create + // succeeds. Nothing was created, so no created chain exists for the authorization loop, yet + // the parent this write publishes into can have become a link after the caller authorized it. + const pinned = path.resolve("/ws/a") + const parent = path.join(pinned, "new") + const escapedParent = path.resolve("/outside/new") + const target = path.join(parent, "target.txt") + function _scenario(parentResolvesElsewhere: boolean, pinGiven: boolean) { + vi.mocked(fs.realpath).mockImplementation(async (p) => { + const s = String(p) + if (parentResolvesElsewhere && s === parent) return escapedParent + return s + }) + // Node 22 reports undefined for a recursive mkdir whose final directory already exists. + vi.mocked(fs.mkdir).mockResolvedValue(undefined) + vi.mocked(fsSync.openSync).mockReturnValue(1) + return pinGiven ? [{ dir: pinned, dev: 1n, ino: 100n, resolvedPath: pinned }] : undefined + } + beforeEach(() => { + mockDefaults() + vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) => + typeof args[3] === "number" ? args[3] : 0, + ) + }) + it("refuses to publish when the parent that already existed resolves under nothing the caller pinned", async () => { + const pin = _scenario(true, true) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedAncestorIdentities: pin, + }) + await expect(promise).rejects.toBeInstanceOf(AncestorReplacedError) + await expect(promise).rejects.toThrow(/nothing the caller authorized/) + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) + it("publishes when the parent that already existed resolves inside the location the caller pinned", async () => { + const pin = _scenario(false, true) + await expect( + safeWriteText(target, "data", { platform: "linux", expectedAncestorIdentities: pin }), + ).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }) + it("publishes when the parent already existed and the caller pinned no location", async () => { + const pin = _scenario(true, false) + await expect( + safeWriteText(target, "data", { platform: "linux", expectedAncestorIdentities: pin }), + ).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }) + it("refuses to publish when only the path form of the name pin is given and its parent resolves outside", async () => { + _scenario(true, false) + const promise = safeWriteText(target, "data", { + platform: "linux", + expectedResolvedPath: target, + }) + await expect(promise).rejects.toBeInstanceOf(AncestorReplacedError) + await expect(promise).rejects.toThrow(/nothing the caller authorized/) + expect(fs.rename).not.toHaveBeenCalled() + expect(fs.link).not.toHaveBeenCalled() + }) + it("publishes when only the path form of the name pin is given and its parent resolves in place", async () => { + // The accept path of the guard this block established. The narrowing that sends every + // path-only pin through the effective-parent check left the reject case tested and the + // accept case untested, so a regression that refused every path-only pin - publishing + // nothing for a parent that resolved exactly where the caller pinned it - would have + // passed this suite. + _scenario(false, false) + await expect( + safeWriteText(target, "data", { platform: "linux", expectedResolvedPath: target }), + ).resolves.toBeUndefined() + expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), target) + }) +}) diff --git a/src/services/file-safety/safeWriteText.ts b/src/services/file-safety/safeWriteText.ts new file mode 100644 index 0000000000..f820356cf2 --- /dev/null +++ b/src/services/file-safety/safeWriteText.ts @@ -0,0 +1,1319 @@ +import * as fs from "fs/promises" +import * as fsSync from "fs" +import * as path from "path" +import { execFile } from "child_process" + +import { getErrorCode } from "../../utils/errorCode" + +export interface SafeWriteTextOptions { + /** + * + * When true, keep a durable copy of the previous content at a sibling + * safeWriteText.bak_* file for the duration of the write: the target is copied + * before the commit rename and the copy is removed after it. The copy is never + * a rollback source - nothing is restored on failure, because the copy never + * displaced the target: before the commit the target still holds its previous + * content, and after it the target holds the new content and this call removes + * the copy. A removal that fails AFTER the commit reports OrphanedPublishedBackupError + * and leaves the new content at the target: nothing is rolled back, because rolling back + * would replace published bytes with an older copy the caller never asked to restore. A + * removal that fails after a write that never committed reports + * OrphanedBackupAfterFailedWriteError, whose contentPublished says which of the two + * happened. When false (default) the atomic rename simply replaces the target -- + * crash-safe window is zero. + */ + backup?: boolean + + /** + * Platform override for testing. When omitted the real process.platform + * value is used. Set to "win32" or "linux" / "darwin" from tests so that + * both branches are reachable without needing a real Windows runner. + */ + platform?: string + + /** + * Custom execFile runner for testing (e.g. vi.fn). When omitted the real + * child_process.execFile is used. + */ + execFileRunner?: typeof execFile + + /** + * Pre-written temp path to use for the commit phase. When provided, + * safeWriteText skips creating its own staging file and uses this path + * instead (it still fsyncs before rename). Useful when a caller has + * already written data to a temp file via a custom stream. + */ + tempPath?: string + + /** + * Commit only if the target name does NOT exist at commit time. + * rename(2) has no no-replace form - it silently displaces a target that another + * writer created after the caller's absence check - so the commit is done with + * link(2) instead, which fails EEXIST for an existing name (and does not follow a + * symlink placed at that name). A conditional create therefore cannot overwrite a + * file it never saw. + */ + failIfExist?: boolean + + /** + * The publish target the caller already authorized. + * A caller that checks workspace containment and then calls this primitive resolves + * the path twice: once for its own decision and once here. If a link is swapped in + * between the two, the decision was about a different file than the one published. + * Passing the authorized value makes that drift fatal instead of silent. + */ + expectedResolvedPath?: string + + /** + * The directories the caller walked when it authorized this target, with the + * (dev, ino) identity each had at that moment. + * + * expectedResolvedPath pins the NAME this write publishes; it cannot see a parent + * directory being replaced by a link between the caller's containment check and the + * commit. Re-checking the ancestor identities immediately before the commit makes a + * swapped parent fatal too: the publish then aborts instead of writing through the new + * link. Node has no descriptor-relative rename, so a swap that lands after this check + * and before the rename is not eliminable here - it narrows the window to the commit + * itself rather than the whole guard. + * The identity check is paired with a realpath comparison: moving a directory + * preserves (dev, ino), and replacing its old name with a symlink to the moved + * location keeps stat() matching while sending the commit to the new location. + * The name must still resolve to the location it was authorized against - the + * recorded resolvedPath when the caller walked a symlink alias, and dir itself + * when it recorded a plain spelling - not merely to the same inode. + */ + expectedAncestorIdentities?: DirectoryIdentity[] + + /** + * Cancellation of an in-flight write. + * + * Every step before the commit is awaited, so a caller that loses interest - a document closed, + * a task abandoned - has one point where the publish can still be refused: the commit gate, after + * the staging file and any backup copy exist and before the target name is moved. An aborted + * signal refuses, the failure cleanup removes this write's staging file, and the target keeps the + * content it had. An abort arriving after this gate cannot be observed - there is no await left + * between here and the rename - so that commit completes. + */ + signal?: AbortSignal +} + +/** One directory's on-disk identity, read with bigint stats so NTFS 64-bit values survive. */ +export type DirectoryIdentity = { + dir: string + dev: bigint + ino: bigint + /** + * Where `dir` resolved to when this identity was taken (its realpath). + * + * A caller that authorized a chain running THROUGH a symlink alias records the alias + * spelling as `dir`; that alias's realpath legitimately differs from `dir` while nothing + * moved, so comparing the current realpath against `dir` alone refuses a write whose + * ancestry never changed. The pre-commit revalidation compares against this value when it + * is present, and against `dir` when it is not. + */ + resolvedPath?: string +} + +/** + * The backup copy could not be created AND the partial copy could not be removed. + * The write failed either way, but the leftover is a copy of the previous content that + * is still on disk: its path travels on the error so the caller can remove it, instead + * of the cleanup silently discarding the only reference to it. + */ +export class OrphanedBackupError extends Error { + readonly orphanedBackupPath: string + readonly originalError: unknown + readonly cleanupError: unknown + constructor(backupPath: string, targetPath: string, cause: unknown, cleanupError: unknown) { + super(_orphanedBackupMessage(targetPath, backupPath, cause, cleanupError), { cause }) + this.name = "OrphanedBackupError" + this.orphanedBackupPath = backupPath + this.originalError = cause + this.cleanupError = cleanupError + } +} + +/** + * The write committed and the content is published, but the pre-write backup could not be + * removed after two attempts (a transient handle - antivirus scanner, indexer - usually + * causes this). Returning success would hide a stale copy of the previous content that + * only a recovery tool can find, so the path travels on this error instead. + */ +export class OrphanedPublishedBackupError extends Error { + readonly publishedPath: string + readonly orphanedBackupPath: string + readonly cleanupError: unknown + + constructor(targetPath: string, backupPath: string, cleanupError: unknown) { + const reason = cleanupError instanceof Error ? cleanupError.message : String(cleanupError) + super( + `safeWriteText: the content was published at ${targetPath}, but the pre-write copy at ${backupPath} ` + + `could not be removed (${reason}). The copy is still on disk and should be removed by the caller or a recovery tool.`, + { cause: cleanupError }, + ) + this.name = "OrphanedPublishedBackupError" + this.publishedPath = targetPath + this.orphanedBackupPath = backupPath + this.cleanupError = cleanupError + } +} + +/** + * A write that is already failing left its complete backup copy on disk because removing it + * failed twice. Reported separately from OrphanedPublishedBackupError, which says the write + * SUCCEEDED and only the copy is leftover: here the write's own failure is the primary fact + * and is kept as originalError (and as this error's cause), cleanupError says why the copy is + * still there, and contentPublished says which of the two meanings the leftover has - a stale + * copy beside published content, or a duplicate of the content the target still holds. + */ +export class OrphanedBackupAfterFailedWriteError extends Error { + readonly targetPath: string + readonly orphanedBackupPath: string + readonly originalError: unknown + readonly cleanupError: unknown + readonly contentPublished: boolean + + constructor( + targetPath: string, + backupPath: string, + cause: unknown, + cleanupError: unknown, + contentPublished: boolean, + ) { + const reason = (error: unknown): string => (error instanceof Error ? error.message : String(error)) + super( + `safeWriteText: the write to ${targetPath} failed (${reason(cause)}), and the backup copy at ${backupPath} ` + + `could not be removed (${reason(cleanupError)}). The copy of the previous content is still on disk; ` + + (contentPublished + ? `the target holds the new content, so the copy is stale and must be removed.` + : `the target still holds the previous content, so the copy duplicates it and must be removed.`), + { cause }, + ) + this.name = "OrphanedBackupAfterFailedWriteError" + this.targetPath = targetPath + this.orphanedBackupPath = backupPath + this.originalError = cause + this.cleanupError = cleanupError + this.contentPublished = contentPublished + } +} + +function _orphanedBackupMessage(targetPath: string, backupPath: string, cause: unknown, cleanupError: unknown): string { + const reason = (error: unknown): string => (error instanceof Error ? error.message : String(error)) + return ( + `safeWriteText: could not create the backup of ${targetPath} (${reason(cause)}), and the ` + + `partial copy at ${backupPath} could not be removed (${reason(cleanupError)}). The copy is ` + + `still on disk and must be deleted.` + ) +} + +/** + * A caller-supplied staging path that is not a file this write may publish: it + * sits outside the target's directory (so the commit rename would cross + * filesystems) or is not a regular file. Rejecting it before any write keeps the + * target from being replaced by whatever the path points at. + */ +export class StagingPathError extends Error { + readonly stagingPath: string + + constructor(message: string, stagingPath: string) { + super(message) + this.name = "StagingPathError" + this.stagingPath = stagingPath + } +} + +/** + * The commit rename succeeded but the parent-directory fsync did not, so the + * directory entry is not known to be durable. The content is at the target; the + * caller cannot assume it survives a crash. Reported as its own error so a + * successful return never claims durability the filesystem did not grant. + */ +export class PostCommitDurabilityError extends Error { + readonly targetPath: string + + constructor(targetPath: string, cause: unknown, copiedTargetFsync = false) { + super( + copiedTargetFsync + ? "The exclusive copy committed but the copied target could not be fsynced -- the content is at the target path reported on this error, and it may not survive a crash on a volume without hard links." + : "The rename committed but the parent directory could not be fsynced -- the content is at the target path reported on this error, and the directory entry may not be durable.", + { cause }, + ) + this.name = "PostCommitDurabilityError" + this.targetPath = targetPath + } +} + +/** + * The target exists but its access rights could not be inspected or saved, so publishing would + * replace it with a file that inherits different rights. On Windows the publish is refused before + * anything is committed: a save that silently widened who can read the file is not a save the + * caller can trust, and nothing has been published yet, so the target still holds its content. + * causeError carries the platform failure behind the refusal - the access check + * error or the icacls error - so a caller can tell a command that ran and refused + * from one that could not be started at all; it is the runner's own error, not a + * summary of it. + */ +export class DaclInspectionError extends Error { + constructor( + readonly targetPath: string, + readonly phase: "inspect" | "save", + readonly causeError: unknown, + ) { + const detail = phase === "save" ? "its DACL could not be saved" : "its access rights could not be checked" + super(`safeWriteText: refusing to publish over ${targetPath} because ${detail}`) + this.name = "DaclInspectionError" + } +} + +/** + * A conditional create (failIfExist) found a target at commit time. The write is + * refused without touching it: whatever is at the path was created by someone else + * and stays exactly as it is. + */ +export class TargetExistsError extends Error { + readonly targetPath: string + constructor(targetPath: string) { + super(`A file already exists at ${targetPath} -- the no-replace commit refused it.`) + this.name = "TargetExistsError" + this.targetPath = targetPath + } +} + +/** + * A conditional create (failIfExist) found that the volume hosting the target has + * no atomic no-replace primitive: link(2) reported that hard links do not exist + * here, and publishing by copy would put bytes at the final name that readers can + * observe mid-copy. Nothing is published - the write fails closed so a retry on a + * capable volume (or a caller that accepts non-atomic publication) decides. + */ +export class UnsupportedFilesystemError extends Error { + readonly targetPath: string + constructor(targetPath: string, cause: unknown) { + super( + `Filesystem hosting ${targetPath} has no atomic no-replace commit primitive -- the guarded create refused to publish by copy.`, + { cause }, + ) + this.name = "UnsupportedFilesystemError" + this.targetPath = targetPath + } +} + +/** + * The path resolved to something other than the target the caller authorized. + * Nothing is staged or published: a link swapped in after the caller's containment + * check would otherwise send the write to a file that check never covered. + */ +export class TargetMovedError extends Error { + readonly authorizedPath: string + readonly resolvedPath: string + constructor(authorizedPath: string, resolvedPath: string) { + super( + `The write was authorized for ${authorizedPath}, but that path now resolves to ${resolvedPath} -- nothing was published.`, + ) + this.name = "TargetMovedError" + this.authorizedPath = authorizedPath + this.resolvedPath = resolvedPath + } +} + +/** + * A directory the caller walked on its way to the authorized target is no longer the + * directory it was: it was removed, replaced, or turned into a link to somewhere else. + * Publishing through it would act on a decision that was never made about the file now + * reachable there, so the commit is aborted. + */ +export class AncestorReplacedError extends Error { + readonly directory: string + constructor(directory: string, reason: string) { + super(`A directory on the authorized path (${directory}) ${reason} -- nothing was published.`) + this.name = "AncestorReplacedError" + this.directory = directory + } +} +/** + * The caller cancelled this write at the commit gate. Nothing was published: the target holds what it + * held before the call, and this write's staging file is removed by the same cleanup that handles every + * other failure. + */ +export class PublishCancelledError extends Error { + readonly targetPath: string + + constructor(targetPath: string) { + super(`The write to ${targetPath} was cancelled before the commit -- nothing was published.`) + this.name = "PublishCancelledError" + this.targetPath = targetPath + } +} + +// -- helpers --------------------------------------------------------------- + +/** fsync one directory so the entry it holds (a rename, or a newly created child) is durable. */ +function _syncDirectory(dir: string): void { + const dirFd = fsSync.openSync(dir, "r") + try { + fsSync.fsyncSync(dirFd) + } finally { + fsSync.closeSync(dirFd) + } +} + +/** Where the caller said a directory was, taken from the pins it handed in. */ +type AuthorizedLocation = { dir: string; location: string; identityBacked: boolean } + +function _authorizedAncestorLocations(options?: SafeWriteTextOptions): AuthorizedLocation[] { + const locations: AuthorizedLocation[] = [] + for (const identity of options?.expectedAncestorIdentities ?? []) { + locations.push({ + dir: path.resolve(identity.dir), + location: path.resolve(identity.resolvedPath ?? identity.dir), + identityBacked: true, + }) + } + if (options?.expectedResolvedPath) { + const pinnedDir = path.dirname(path.resolve(options.expectedResolvedPath)) + locations.push({ dir: pinnedDir, location: pinnedDir, identityBacked: false }) + } + return locations +} + +/** True when *target* is *dir* itself or under it on the same spelling. */ +function _isInside(dir: string, target: string): boolean { + const rel = path.relative(dir, target) + // A relative answer that comes back absolute is on another root - another drive on + // Windows - and no descendant of *dir* spells itself that way. + if (path.isAbsolute(rel)) { + return false + } + // Only a traversal segment on its own leaves *dir*. A name that merely begins with two + // dots, the way a directory named ..cache does, is an ordinary child of *dir*, and the + // blanket test above refused descendants the caller had pinned by its own name. The first + // segment is taken the way the platform that produced this path divides segments: both + // spellings of the separator divide them on Windows, only the slash divides them + // elsewhere. An empty first segment is *dir* itself, which is inside it. + const firstSegment = rel.split(path.sep === "\\" ? /[\\/]/ : path.sep)[0] + return firstSegment !== ".." +} + +/** The deepest pinned location that contains *target*, if the caller pinned one. */ +function _deepestAuthorizedLocation(locations: AuthorizedLocation[], target: string): AuthorizedLocation | undefined { + let deepest: AuthorizedLocation | undefined + for (const candidate of locations) { + if ( + _isInside(candidate.location, target) && + (!deepest || candidate.location.length > deepest.location.length) + ) { + deepest = candidate + } + } + return deepest +} + +/** The deepest location the caller pinned that contains the *name* at *target*. + * + * Selection here is by the spelling the caller authorized, never by where the thing on + * disk happens to resolve to. For a pin built from expectedResolvedPath those are the same + * string. For an identity pin the caller walked a name, so the name is the comparison, and + * where the caller walked through a symlink alias it recorded the location that alias + * resolved to, which stands for the same decision and is compared as well. What the + * resolved path of *target* is reserved for is the containment check the caller's decision + * feeds: a selection that used it would let a directory created under a deep pin move + * itself under a shallower one by becoming a link, and pass the check that was supposed to + * catch exactly that. + */ +function _deepestPinnedDirectory(locations: AuthorizedLocation[], target: string): AuthorizedLocation | undefined { + let deepest: AuthorizedLocation | undefined + let deepestMatchLength = -1 + for (const candidate of locations) { + // Either spelling is the caller's own decision: the name it walked, or the location + // it recorded that name resolving to when it walked through a symlink alias. A + // path-form pin has no separate spelling, so its two fields are the same string. + const underTheNamedSpelling = _isInside(candidate.dir, target) + const underTheAuthorizedLocation = _isInside(candidate.location, target) + if (!underTheNamedSpelling && !underTheAuthorizedLocation) { + continue + } + // Depth is measured on the spelling that matched. A pin that reaches the name only + // through the location its alias resolved to authorized shallower ground than a pin + // whose own name contains it, and ranking the candidates by the length of their dir + // field let a long alias spelling outrank a deeper name: the containment check that + // follows then ran against the shallower location, and a directory created under the + // deeper pin that had become a link into the shallower one passed it. + const matchedSpelling = underTheNamedSpelling ? candidate.dir : candidate.location + if (matchedSpelling.length > deepestMatchLength) { + deepest = candidate + deepestMatchLength = matchedSpelling.length + } + } + return deepest +} + +/** Re-apply the target's group to the staging descriptor before publication. + * + * The commit publishes this inode, so whatever the staging file carries when the descriptor closes is + * what the target gets afterwards. The mode is re-applied with fchmodSync above; the group is the other + * half of what a shared workspace's read access lives on, and nothing carried it. -1 leaves the owner + * alone. + * + * Best-effort on purpose. Measured on Windows the call reports success and changes nothing (the gid + * stays 0 after asking for another group), and on POSIX a caller allowed to write a file is not always + * a caller allowed to change its group, so failing here would refuse writes this user may make. The + * attempt is the contract; the effect is platform-owned. */ +function _preserveGroup(fd: number, gid: number): void { + try { + fsSync.fchownSync(fd, -1, gid) + } catch { + // A group this user cannot take is carried by the mode copy and the ACL path, not by failing the write. + } +} + +/** + * The directories *mkdir(recursive:true)* had to create for *dirPath*, outermost first. + * + * Node reports the outermost component it created - or nothing when the path already existed - + * and that answer is the whole input, so no extra stat is needed to learn what appeared. The + * commit rename only makes the entry INSIDE the immediate parent durable, and every newly + * created directory is itself an entry in its own parent, so step 4b fsyncs this chain (deepest + * first, after the immediate parent) and then the directory that first links it into the tree; + * otherwise a crash can drop an ancestor and with it the published file. + * + * On Windows the reported path carries the extended-length namespace marker, which is stripped + * so the chain compares in the spelling the write itself works in. The marker has two shapes: the + * drive shape \\\?C:\... and the UNC shape \\\?UNC\server\share\..., + * whose root is spelled \\server\share\... once the marker is gone. Removing only the marker + * characters from the UNC shape leaves \UNC\server\share\..., which reads as a path relative + * to the current drive, so the walk below finds no root and yields nothing: the created-directory + * authorization that reads this answer is skipped with it, and a directory this write created + * under a planted link goes unchecked. The UNC shape is therefore converted as its own case. An + * answer that is not on this path yields nothing, rather than syncing directories this write + * cannot place. + */ +function _createdAncestorChain(createdRoot: string | undefined, dirPath: string): string[] { + if (typeof createdRoot !== "string") return [] + const namespacePrefix = "\\\\?\\" + const uncNamespacePrefix = "\\\\?\\UNC\\" + let unprefixed = createdRoot + if (createdRoot.startsWith(uncNamespacePrefix)) { + // The marker and the "UNC" label together stand for the leading \\, so the + // converted spelling restores that root instead of leaving the label as a relative + // first segment. + unprefixed = "\\\\" + createdRoot.slice(uncNamespacePrefix.length) + } else if (createdRoot.startsWith(namespacePrefix)) { + unprefixed = createdRoot.slice(namespacePrefix.length) + } + const root = path.resolve(unprefixed) + const chain: string[] = [] + let cursor = dirPath + for (;;) { + chain.push(cursor) + if (cursor === root) return chain.reverse() + const parent = path.dirname(cursor) + if (parent === cursor) return [] + cursor = parent + } +} + +/** Generate a unique temp file name in the given directory. */ +function _tempName(dir: string, prefix: string): string { + return path.join(dir, "." + prefix + "_" + Date.now() + "_" + Math.random().toString(36).substring(2) + ".tmp") +} + +/** Create a private per-write staging sub-directory inside *dir*. The name is + * unique per write, so concurrent writes never collide on their temp names and + * never remove a staging directory another write is still using: with one shared + * name, one write's best-effort rmdir could delete the directory another write + * had just created but not yet opened, failing its openSync with ENOENT. */ +function _stagingDir(dir: string): string { + const sd = path.join(dir, ".file-safety-staging_" + Date.now() + "_" + Math.random().toString(36).substring(2)) + // mode:0o700 protects a freshly created staging dir; the best-effort chmod + // repairs a pre-existing one (mkdirSync with recursive:true never chmods an + // existing directory), so staged temp files are never group/world readable. + fsSync.mkdirSync(sd, { recursive: true, mode: 0o700 }) + try { + fsSync.chmodSync(sd, 0o700) + } catch { + // best-effort: chmod denied or unavailable; a fresh dir was still + // created with the requested mode + } + return sd +} + +async function _runIcacls(args: string[], execFileRunner?: typeof execFile): Promise { + const runner = execFileRunner ?? execFile + await new Promise((resolve, reject) => { + runner("icacls", args, { windowsHide: true }, (err) => (err ? reject(err) : resolve())) + }) +} + +/** Canonicalize *target*, treating only a vanished name as no answer. A real inspection + * failure - EACCES, EIO - is the caller's to report, never to answer with undefined. */ +async function _realpathUnlessGone(target: string): Promise { + return fs.realpath(target).catch((error: unknown) => { + const code = getErrorCode(error) + if (code === "ENOENT" || code === "ENOTDIR") { + return undefined + } + throw error + }) +} + +/** Remove a leftover copy, retrying once: a transient handle - an antivirus scanner or an + * indexer - blocks the first unlink on Windows, and ENOENT is the outcome the cleanup wanted. + * Answers null when the path is gone and the last error when it is not. */ +async function _removeBackupWithRetry(backupPath: string): Promise { + let removalError: unknown = null + for (let attempt = 0; attempt < 2; attempt++) { + try { + await fs.unlink(backupPath) + removalError = null + break + } catch (cleanupError: unknown) { + if (getErrorCode(cleanupError) === "ENOENT") { + removalError = null + break + } + removalError = cleanupError + } + } + return removalError +} + +/** The mode, group and presence of the publish target, captured once per write. Only a + * vanished target answers "nothing to carry"; any other stat failure is the caller's to raise. */ +function _captureTargetIdentity(targetPath: string): { mode: number | null; gid: number | undefined; exists: boolean } { + try { + const stats = fsSync.statSync(targetPath) + return { mode: stats.mode & 0o777, gid: typeof stats.gid === "number" ? stats.gid : undefined, exists: true } + } catch (error: unknown) { + if (getErrorCode(error) !== "ENOENT") throw error + return { mode: null, gid: undefined, exists: false } + } +} +/** Carry the captured identity onto the staging descriptor, on the open fd rather than on + * the path, so a read-only target does not make the open itself fail. */ +function _applyTargetIdentity(fd: number, mode: number, gid: number | undefined): void { + fsSync.fchmodSync(fd, mode) + if (gid !== undefined) { + _preserveGroup(fd, gid) + } +} + +/** Save the DACL of *srcPath* to a dump file on Windows. + * Returns null when the dump was written - the caller keeps it and restores it onto the + * committed file at step 5 - and returns the runner's error when it was not, because the + * caller refuses the publish in that case and has to be able to say which failure it is + * refusing: "icacls ran and failed" and "icacls could not be started at all" are different + * facts to act on. Never throws. */ +async function _saveDaclWindows(srcPath: string, dumpPath: string, execFileRunner?: typeof execFile): Promise { + try { + await _runIcacls([srcPath, "/save", dumpPath, "/T"], execFileRunner) + return null + } catch (error: unknown) { + return error + } +} +/** Restore a DACL dump onto *dirPath* on Windows. + * Best-effort: content is already committed, so failure is non-fatal. */ +async function _restoreDaclWindows(dirPath: string, dumpPath: string, execFileRunner?: typeof execFile): Promise { + try { + await _runIcacls([dirPath, "/restore", dumpPath], execFileRunner) + } catch { + // best-effort; content already committed + } +} + +// -- public API ------------------------------------------------------------ + +/** + * Resolve the publish target: the symlink referent when the given path is an + * existing symlink, the path itself otherwise. Only ENOENT (target absent yet) + * may fall back to the given path; any other resolution error (EACCES, EIO, ...) + * propagates so a broken or unreadable symlink is never written through its + * link path. Callers that stage a temp file themselves must stage it beside + * the resolved path: the commit is a rename onto the referent, and a rename + * across filesystems fails with EXDEV. + */ +export async function resolvePublishTarget(absoluteFilePath: string): Promise { + return fs.realpath(absoluteFilePath).catch(async (error: unknown) => { + if (getErrorCode(error) !== "ENOENT") throw error + // ENOENT also covers a dangling symlink, which must never be written through. + // Only a lstat that also reports the path as absent may fall back to the + // given path; a real lstat failure (EACCES, EIO) says nothing about whether + // the path is a link, so falling back would write through a link we were + // simply not allowed to inspect. + const linkStat = await fs.lstat(absoluteFilePath).catch((lstatError: unknown) => { + if (getErrorCode(lstatError) === "ENOENT") return undefined + throw lstatError + }) + if (linkStat?.isSymbolicLink()) throw error + return await canonicalizeNearestAncestor(absoluteFilePath) + }) +} + +/** + * Canonicalize the parent directory and re-join the basename. fs.realpath + * canonicalizes every component, including a symlinked ancestor directory or a + * Windows 8.3 short name, so a lock key must be canonical even when the file + * itself is not there yet -- otherwise the key for one file depends on whether + * the file exists when the key is computed, and two writers take two locks. + */ + +async function canonicalDirKey(absoluteFilePath: string): Promise { + const dirPath = path.dirname(absoluteFilePath) + // Walk up to the nearest ancestor that EXISTS, canonicalize that, and re-join the + // components that are not there yet. Falling back to the unresolved spelling of the + // whole parent - what a single realpath(...).catch(() => dirPath) used to do - makes + // the key depend on whether the directory happens to exist: a writer whose parent is + // already there canonicalizes through a symlinked ancestor (or a short name) while a + // writer racing to create the same directory gets the literal spelling, so the two + // take different locks for one file and a read-modify-write loses one side. + // A realpath failure that is not "not there yet" says nothing about the canonical + // form, so it is propagated rather than papered over with a key that may be wrong. + let cursor = dirPath + const missing: string[] = [] + for (;;) { + const canonical = await fs.realpath(cursor).catch((error: unknown) => { + if (getErrorCode(error) === "ENOENT") return undefined + throw error + }) + if (canonical !== undefined) { + return path.join(canonical, ...missing.reverse(), path.basename(absoluteFilePath)) + } + missing.push(path.basename(cursor)) + const parent = path.dirname(cursor) + if (parent === cursor) { + // Every component up to the root is missing: there is nothing to canonicalize + // against, and the literal path is the only key left. + return path.join(dirPath, path.basename(absoluteFilePath)) + } + cursor = parent + } +} + +/** + * Canonicalize the nearest EXISTING ancestor and re-append the missing components. + * The guard hands back a pin produced exactly this way (guardedWrite#realpathNearest), + * so an absent target has to resolve identically here: a lexical fallback differs from + * that pin whenever an ancestor is a symlink, and the create would then abort with + * TargetMovedError even though nothing moved. + */ +async function canonicalizeNearestAncestor(absoluteFilePath: string): Promise { + const missing: string[] = [] + let cursor = absoluteFilePath + for (;;) { + try { + const realPath = await fs.realpath(cursor) + return missing.length > 0 ? path.join(realPath, ...missing.reverse()) : realPath + } catch (error: unknown) { + const code = getErrorCode(error) + if (code !== "ENOENT" && code !== "ENOTDIR") { + // A real inspection failure (EACCES, EIO) says nothing about the path's + // identity. Returning a lexical key here would silently canonicalize a + // different path than the guard's pin, so fail closed instead. + throw error + } + const parent = path.dirname(cursor) + if (parent === cursor) return absoluteFilePath + missing.push(path.basename(cursor)) + cursor = parent + } + } +} + +/** + * Lock key for a publish target: the symlink referent when the path is an + * existing symlink, the path itself otherwise. Unlike resolvePublishTarget this + * tolerates a dangling link, because the lock key has to be computable while a + * peer writer is mid-commit (backup mode renames the referent away and back). + * The walk is bounded so a two-link cycle terminates, and every key it returns is + * canonicalized through canonicalDirKey. + */ +export async function resolveLockKey(absoluteFilePath: string): Promise { + try { + return await canonicalDirKey(await resolvePublishTarget(absoluteFilePath)) + } catch { + // A real readlink throws for anything that is not a link, so a normal chain + // ends the walk. Two links that point at each other never would, so the + // walk is bounded and callers use the key they actually reached. + let key = absoluteFilePath + for (let depth = 0; depth < 8; depth++) { + const target = await fs.readlink(key).catch(() => undefined) + if (target === undefined) return await canonicalDirKey(key) + key = await canonicalDirKey(path.resolve(path.dirname(key), target)) + } + return await canonicalDirKey(key) + } +} + +export async function safeWriteText( + filePath: string, + content: string | Uint8Array, + options?: SafeWriteTextOptions, +): Promise { + const absoluteFilePath = path.resolve(filePath) + + // Resolve the symlink referent (see resolvePublishTarget). + const targetPath = await resolvePublishTarget(absoluteFilePath) + + // The caller authorized a specific resolved path; publishing at a different one + // would act on a decision that was never made about this file. + if (options?.expectedResolvedPath && path.resolve(options.expectedResolvedPath) !== targetPath) { + throw new TargetMovedError(options.expectedResolvedPath, targetPath) + } + + const dirPath = path.dirname(targetPath) + + // Ensure parent directory exists (mirrors safeWriteJson behaviour). What mkdir reports it + // created feeds step 4b's fsync of the ancestors this write introduced; see + // _createdAncestorChain. + const createdAncestors = _createdAncestorChain(await fs.mkdir(dirPath, { recursive: true }), dirPath) + await fs.access(dirPath) + + // What mkdir reports it created is a fact about the filesystem, not about the decision the + // caller made: the chain above is sampled from that report, after the fact. A directory the + // caller never walked - because it was not there when the caller authorized - can be a link + // by the time mkdir reaches it, so the parent this write created sits outside the authorized + // chain while still being reported as this write's parent, and the fsync chain alone would + // then sync and publish through it. Pick the location the caller pinned by the NAME each + // created directory carries - never by where that name happens to resolve to - and only + // then compare the resolved directory against it. A created directory under nothing the + // caller pinned has left the authorized chain by construction, and so has one that resolves + // out of the location its own name selected, which is the bypass a resolved-path selection + // hid: a created directory under a deep pin that becomes a link into a shallower pin's + // grounds passed the check meant to catch it. A caller that pinned no location has nothing + // to compare against and keeps its current behaviour. + if (createdAncestors.length > 0) { + const authorized = _authorizedAncestorLocations(options) + if (authorized.length > 0) { + for (const created of createdAncestors) { + // A name that vanished since the mkdir is reported by the ancestry recheck below, which + // also knows whether the caller authorized that name; only a real inspection failure is + // this write's to report here. + const createdReal = await _realpathUnlessGone(created) + // Selected by the name, so a redirect of the created directory cannot move the + // answer to a shallower pin; the resolved directory is compared against the + // selection below rather than feeding it. + const pinned = _deepestPinnedDirectory(authorized, created) + if (pinned === undefined) { + throw new AncestorReplacedError(created, "was created under nothing the caller authorized") + } + if (createdReal !== undefined && !_isInside(pinned.location, createdReal)) { + throw new AncestorReplacedError(created, "was created outside the authorized location") + } + } + } + } else { + // Nothing was created, which is what Node 22 reports when the final directory was already + // there -- including when it is a symbolic link to a directory, because the stat that follows + // the create succeeds and names no first created path. No chain means the loop above never + // ran, yet the parent this write publishes into can still have become a link after the caller + // authorized it: /ws/a pinned, /ws/a/new absent while the target was resolved, the name + // planted as a link to /outside before the mkdir, and the access check above follows that link + // and passes. The effective parent is checked the way the created chain is checked, so a + // parent that resolves under nothing the caller pinned is refused before anything is staged. + const authorized = _authorizedAncestorLocations(options) + // A parent the caller named by identity belongs to the ancestry recheck below: that check + // holds the (dev, ino) pair and the resolution the caller authorized against, and it reports + // a moved or re-pointed pin in those terms. A pin built from expectedResolvedPath carries no + // identity, so that recheck has nothing to compare for it and this branch must judge the + // parent it names: only identity-backed pins count as named here. + const resolvedParent = path.resolve(dirPath) + const namedByCaller = authorized.some((pin) => pin.identityBacked && pin.dir === resolvedParent) + if (authorized.length > 0 && !namedByCaller) { + // A parent that vanished since the mkdir is reported by the ancestry recheck below, which + // knows whether the caller authorized that name; only a real inspection failure is this + // write's to report here. + const parentReal = await _realpathUnlessGone(dirPath) + const pinned = _deepestAuthorizedLocation(authorized, parentReal ?? dirPath) + if (pinned === undefined) { + throw new AncestorReplacedError(dirPath, "resolves under nothing the caller authorized") + } + if (parentReal !== undefined && !_isInside(pinned.location, parentReal)) { + throw new AncestorReplacedError(dirPath, "resolves outside the authorized location") + } + } + } + + // Create the staging directory only when we generate the temp file there; + // callers supplying their own tempPath (e.g. safeWriteJson) must not be left + // with an empty .file-safety-staging directory behind. Track the directory this + // write created so its cleanup removes its own directory, not a shared one. + let stagingDir: string | null = null + let tempPath: string + // Whether the commit rename has consumed the staging file. Cleanup is allowed to unlink + // the staging path only while this write still owns it: after the rename the name belongs to + // whatever is filed under it next, and a caller-supplied staging name is reused by the next + // write to the same target. + let stagingCommitted = false + if (options?.tempPath) { + // A caller-supplied staging file is only safe when it is the file this + // write is staging, not an arbitrary path. Two properties are checked: + // it must sit beside the resolved target (a rename across filesystems + // fails with EXDEV, and a path elsewhere lets a caller publish an + // unrelated file onto the target), and it must be a regular file rather + // than a link — renaming a link over the target publishes whatever the + // link points at, which is the same trust problem as writing through a + // dangling symlink in resolvePublishTarget. + const supplied = path.resolve(options.tempPath) + if (path.dirname(supplied) !== path.resolve(dirPath)) { + throw new StagingPathError( + `Staging file must sit in the target's directory (${dirPath}), got ${supplied}`, + supplied, + ) + } + // BigInt stats: on NTFS/ReFS the file identity can exceed Number.MAX_SAFE_INTEGER, and + // a rounded number makes two different files look identical (rejecting a valid staging + // file) or hides a real alias. + const stagingStat = await fs.lstat(supplied, { bigint: true }) + if (stagingStat.isSymbolicLink() || !stagingStat.isFile()) { + throw new StagingPathError( + `Staging file must be a regular file, not ${stagingStat.isSymbolicLink() ? "a symlink" : "another file type"}`, + supplied, + ) + } + // A staging path that is the target would be unlinked by the failure handler + // while it still holds the only copy of the content, so a failed write would + // delete the file it was meant to protect. Compare identities, not spellings: + // an alias of the target is the same hazard. + // Only a missing target may be skipped: an EACCES/ELOOP/ENOTDIR here means the + // identity comparison could not be made, and treating that as "no target" would let a + // staging alias reach the commit and let cleanup delete the file it was meant to + // protect. + const targetStat = await fs.lstat(targetPath, { bigint: true }).catch((error: unknown) => { + if (getErrorCode(error) !== "ENOENT") { + throw new StagingPathError("Staging file could not be compared with the target", supplied) + } + return null + }) + if ( + targetStat && + typeof stagingStat.ino === "bigint" && + typeof targetStat.ino === "bigint" && + stagingStat.ino === targetStat.ino && + stagingStat.dev === targetStat.dev + ) { + throw new StagingPathError("Staging file must not be the target itself", supplied) + } + // The caller's own path is used as given; only the check is canonical. + tempPath = options.tempPath + } else { + stagingDir = _stagingDir(dirPath) + tempPath = _tempName(stagingDir, "safeWriteText") + } + + let backupPath: string | null = null + let releaseBackupOnSuccess = false + // True only when this write's own seed open created the backup file. A name that already + // existed is not this write's file, and the failure path below must not unlink it. + let backupSeeded = false + // Non-null only when the win32 step-2 block saved a successful DACL dump: + // it gates the step-5 restore and is tracked for the cleanup unlinks. + let daclDumpPath: string | null = null + + try { + // -- Step 1: write content to staging temp file ------------------- + if (!options?.tempPath) { + // Preserve the existing target's permissions: the staging file must + // not be published wider than the file it replaces (a 0o600 target + // must not become 0o644 through the atomic rename). + // Encode before opening the staging file: an encoding Node cannot + // represent must not leave a half-written temp file behind. + // A string is encoded as UTF-8; bytes handed in by the caller (the + // extension host encodes a document with VS Code's own codec, which + // covers the legacy code pages Node cannot represent) are published + // unchanged. + const buffer = Buffer.from(content) + const identity = _captureTargetIdentity(targetPath) + const targetMode = identity.mode ?? 0o644 // default for a fresh target + // openSync's creation mode is narrowed by the process umask, so an + // existing 0o664 target would be published as 0o644 through the + // rename. Apply the existing target's exact mode on the fd, as the + // caller-staged branch does; a fresh target keeps the default mode. + const fd = fsSync.openSync(tempPath, "w", targetMode) + try { + if (identity.exists) { + _applyTargetIdentity(fd, targetMode, identity.gid) + } + // Loop until every byte is written: writeSync can report a short + // (partial) write, and publishing a truncated staging file would + // commit corrupt content. + // A zero return is not a short write - it means the descriptor made no progress - + // and it is handled below rather than looped on. + let offset = 0 + while (offset < buffer.length) { + const written = fsSync.writeSync(fd, buffer, offset, buffer.length - offset) + if (written === 0) { + // Not a short write: the descriptor made no progress at all, so looping again + // would hold the fd and the event loop forever without ever reaching fsyncSync + // or the commit. The finally below closes the fd and the outer cleanup removes + // the staged file, so a stalled write strands neither. + throw new Error( + `safeWriteText: write of ${tempPath} stalled after ${offset} of ${buffer.length} bytes`, + ) + } + offset += written + } + fsSync.fsyncSync(fd) + } finally { + fsSync.closeSync(fd) + } + } else { + // Preserve the existing target's mode (CWE-732): the caller-staged + // temp carries its own creation mode, and publishing it as-is would + // widen a restrictive target (e.g. 0o600 -> 0o644) through rename. + // The mode is applied with fchmodSync on the open fd (AFTER openSync): + // chmodSync on the path before the open would make a read-only target + // (0o400/0o444) fail openSync(tempPath, "r+") with EACCES. + const identity = _captureTargetIdentity(targetPath) + const fd = fsSync.openSync(tempPath, "r+") + try { + if (identity.mode !== null) { + _applyTargetIdentity(fd, identity.mode, identity.gid) + } + fsSync.fsyncSync(fd) + } finally { + fsSync.closeSync(fd) + } + } + + // -- Step 2 (win32): save DACL BEFORE backup rename --------------- + const platform = options?.platform ?? process.platform + if (platform === "win32") { + let accessError: unknown = null + try { + await fs.access(targetPath) // target exists? + } catch (error: unknown) { + accessError = error + } + if (accessError === null) { + const dumpPath = _tempName(dirPath, "safeWriteText.acl") + const saveFailure = await _saveDaclWindows(targetPath, dumpPath, options?.execFileRunner) + if (saveFailure === null) { + // Only a successfully saved dump may be restored onto the + // committed file (step 5). + daclDumpPath = dumpPath + } else { + // A failed icacls may have left a partial dump behind; + // remove it now (best-effort) so no partial dump survives and + // no later step can restore from it. + await fs.unlink(dumpPath).catch(() => {}) + // The target exists and its DACL could not be captured, so the commit rename + // would replace it with a file that inherits different access rights, and nothing + // here can verify an equivalent restrictive ACL on that replacement. The publish is + // refused instead of warned about: a save that silently changed who can read the + // file is not a save the caller can trust. Nothing is committed yet, so the target + // still holds its content, and this throw lands in the handler at the bottom of + // this try - the one place that removes the staged file and this write's own + // staging directory - so a refused publish strands neither. + // The runner's error travels with the refusal: the phase already says which check + // refused, and without the error a caller cannot tell a failed icacls from an + // icacls that could not be started at all. + throw new DaclInspectionError(targetPath, "save", saveFailure) + } + } else if (getErrorCode(accessError) !== "ENOENT") { + // Not "absent": the target is there but its access rights could not be read + // (EACCES, ...), so publishing would replace a file whose rights this call never + // learned. Same rule as the failed save above: refuse before anything is committed. + throw new DaclInspectionError(targetPath, "inspect", accessError) + } + } + + try { + // -- Step 2b: re-validate the authorized ancestry before committing -- + // The caller decided containment by walking this directory chain. A parent + // swapped for a link to outside that chain would send the commit somewhere the + // caller never authorized, even though expectedResolvedPath still matches (the + // name is unchanged). Compare each recorded identity now, before anything is + // moved into place. + if (options?.expectedAncestorIdentities) { + for (const expected of options.expectedAncestorIdentities) { + const current = await fs.stat(expected.dir, { bigint: true }).catch((error: unknown) => { + if (getErrorCode(error) === "ENOENT") { + throw new AncestorReplacedError(expected.dir, "no longer exists") + } + throw error + }) + if (current.dev !== expected.dev || current.ino !== expected.ino) { + throw new AncestorReplacedError(expected.dir, "is no longer the directory that was authorized") + } + // A move preserves dev+ino, so the identity check above passes for a + // directory that was relocated and whose old name was replaced by a + // symlink to the moved location - stat follows that link. The commit + // below takes path strings and would follow it too, publishing at the + // moved location outside the chain the caller walked. Require that the + // authorized name still resolves to the very location it named. + // Only a vanished name is a containment violation. A transient EACCES + // or EIO would otherwise be reported as a replaced ancestor, pointing + // the user at a security problem that is not there - mirror the stat + // call above, which maps only ENOENT and rethrows the rest. + const resolvedDir = await _realpathUnlessGone(expected.dir) + // The location the caller authorized. A recorded resolvedPath is the spelling the + // caller walked - an alias ancestor resolves to something else by definition, and a + // stable alias must pass here; the (dev, ino) check above is what catches the alias + // being re-pointed. Without a resolvedPath the authorized name is the lexical dir. + const authorizedLocation = expected.resolvedPath + ? path.resolve(expected.resolvedPath) + : path.resolve(expected.dir) + if (resolvedDir === undefined || path.resolve(resolvedDir) !== authorizedLocation) { + throw new AncestorReplacedError(expected.dir, "no longer resolves to the authorized location") + } + } + } + + // -- Step 3 (backup:true): durable copy target -> backup ---- + if (options?.backup) { + try { + await fs.access(targetPath) + backupPath = _tempName(dirPath, "safeWriteText.bak") + // Copy, never move. Renaming the target away leaves the canonical path absent for + // the whole commit window: readers see a missing file, and a concurrent + // writer can create a new target that a later rollback would destroy. A copy + // keeps the target present, so the step 4 rename is the only change to the + // canonical path. The copy is flushed so the retained content survives a crash. + try { + // Create the destination BEFORE any content exists at it, with the mode fixed + // at open time. fs.copyFile picks the destination mode itself (the platform + // creation mask subject to umask on some platforms, the source's mode - or its + // read-only attribute - on others), so letting it create the file would either + // leave a restrictive target's bytes briefly readable to others, or leave the + // copy unwritable so the fsync open below fails with EACCES. open() ignores its + // mode argument for an existing file, so this 0o600 survives the copy on POSIX; + // the chmod afterwards is what clears a copied read-only attribute on Windows + // and keeps a backup of a permissive file private. + const seedFd = fsSync.openSync(backupPath, "wx", 0o600) + // The name is ours from the moment the exclusive open succeeds, so the failure + // path may remove it even when the close below reports an error. + backupSeeded = true + // Single close, no retry: on POSIX close(2) can release the descriptor before it + // reports an error (and leaves its state unspecified after EINTR), so a second + // close could release a descriptor some other operation has meanwhile reused. + // The failure propagates; backupPath is already recorded, so the outer cleanup + // removes the seeded file instead of leaving it beside the target. + fsSync.closeSync(seedFd) + await fs.copyFile(targetPath, backupPath) + await fs.chmod(backupPath, 0o600) + // "r+" not "r": fsync on a read-only handle is EPERM on Windows, and the same + // flag the staged temp file uses above. + const backupFd = fsSync.openSync(backupPath, "r+") + try { + fsSync.fsyncSync(backupFd) + } finally { + fsSync.closeSync(backupFd) + } + } catch (backupError: unknown) { + // A partial backup must not outlive this attempt: it is not a complete copy + // of anything, and once the write fails nothing else removes it. The unlink is + // retried once (Windows reports EPERM for a file whose handle has not been + // released yet); if it still fails the path is carried on the thrown error + // instead of being dropped where no caller can act on it. + const orphanPath = backupPath + let backupCleanupError: unknown = null + if (backupSeeded) { + for (let attempt = 0; attempt < 2; attempt++) { + try { + await fs.unlink(orphanPath) + backupCleanupError = null + break + } catch (cleanupError: unknown) { + if (getErrorCode(cleanupError) === "ENOENT") { + // Already gone: that is exactly the outcome the cleanup wanted, so stop + // rather than unlinking the same path a second time. + backupCleanupError = null + break + } + backupCleanupError = cleanupError + } + } + } + backupPath = null + // When the seed open never succeeded - an EEXIST on a name another writer owns, or a + // failure before anything existed at it - there is nothing here to remove: an entry + // this write did not create is not this write's orphan, and unlinking it would take + // away somebody else's backup on the way out. backupCleanupError stays null, so the + // original failure below is what the caller sees. + if (backupCleanupError !== null) { + throw new OrphanedBackupError(orphanPath, targetPath, backupError, backupCleanupError) + } + throw backupError + } + releaseBackupOnSuccess = true + } catch (err: unknown) { + if (getErrorCode(err) !== "ENOENT") throw err + } + } + + // -- Commit gate: a cancelled write publishes nothing ------------------- + // Every step above is awaited, so an abort that arrived at any of them is visible here, and + // this is the last point where publishing can still be refused: the commit below is a + // synchronous rename with no await left between here and it. + if (options?.signal?.aborted) { + throw new PublishCancelledError(targetPath) + } + + // -- Step 4: atomic commit temp -> target --------------------- + if (options?.failIfExist) { + // No-replace commit: link(2) fails EEXIST when the name already exists, + // where a rename would silently displace whatever a non-participating + // writer put there after the caller checked. The staged copy is removed + // once the name points at it. + try { + await fs.link(tempPath, targetPath) + } catch (error: unknown) { + const code = getErrorCode(error) + if (code === "EEXIST") { + throw new TargetExistsError(targetPath) + } + // FAT32/exFAT volumes and some SMB/network mounts have no hard links, where + // link(2) fails EPERM/ENOTSUP/ENOSYS. The fallback this replaces published by + // an exclusive copy directly at the final name, but a copy is not atomic: + // readers can observe a partial file, and a crash or an EIO mid-copy leaves + // damaged bytes under the final name with the 'already exists' verdict on + // retry. No atomic no-replace primitive exists on those volumes, so the + // guarded create fails closed - nothing is published and the caller learns + // the volume cannot honor the contract. + if (code !== "EPERM" && code !== "ENOTSUP" && code !== "ENOSYS") { + throw error + } + throw new UnsupportedFilesystemError(targetPath, error) + } + } else { + await fs.rename(tempPath, targetPath) + } + + if (options?.failIfExist) { + // The target name is published at this point; the staged name is only a second + // link to the same inode (or a copy of it). Removal is best-effort: on Windows + // an antivirus handle can make unlink fail with EBUSY/EPERM after the content + // is already visible, and the write must not be reported as failed for content + // the caller can now read back. + await fs.unlink(tempPath).catch(() => undefined) + } + + // Marked once the commit has consumed the staging name: on the rename path the + // rename consumed it, on the link path the removal just did. Every step after + // this one is a post-commit step, and none of them may remove the staging path + // or the published content. + stagingCommitted = true + // -- Step 4b (POSIX): fsync the parent directory so the directory entry + // changed by the commit rename is durable, not just the file content. + if (platform !== "win32") { + try { + _syncDirectory(dirPath) + // The rename above made the entry INSIDE dirPath durable. A parent this call had to + // create is itself an entry in its own parent, so syncing only the immediate parent + // leaves the newer ancestors unsynced and a crash can remove the chain - taking the + // published file with it. Sync deepest-first, ending with the pre-existing directory + // that holds the outermost new entry. + for (let i = createdAncestors.length - 2; i >= 0; i--) { + _syncDirectory(createdAncestors[i]) + } + if (createdAncestors.length > 0) { + _syncDirectory(path.dirname(createdAncestors[0])) + } + } catch (error: unknown) { + // The content rename committed, but the directory entry that + // points at it is not known to be durable. Reporting success + // here would let a caller believe the write survives a crash, + // so the failure is surfaced as its own error: the caller can + // still find the content at the target, it just cannot rely on + // the directory entry having reached the disk. + throw new PostCommitDurabilityError(targetPath, error) + } + } + + // -- Step 5 (win32): restore DACL AFTER commit rename --------- + // daclDumpPath is non-null only when the win32 step-2 block saved a + // successful dump, so this gate is closed on every other platform + // and on every failed save. + if (daclDumpPath !== null) { + const restoredDir = path.dirname(targetPath) + await _restoreDaclWindows(restoredDir, daclDumpPath, options?.execFileRunner) + } + + // -- Step 6 (backup:true): delete backup on success ----------- + if (releaseBackupOnSuccess && backupPath) { + const orphanedBackupPath = backupPath + // A transient handle (antivirus scanner, indexer) can block the first unlink + // on Windows; one retry usually clears it. + const backupCleanupError = await _removeBackupWithRetry(orphanedBackupPath) + backupPath = null + if (backupCleanupError !== null) { + // The content is published: reporting success here would abandon a stale + // copy of the previous content, so the failure travels as its own error. + throw new OrphanedPublishedBackupError(targetPath, orphanedBackupPath, backupCleanupError) + } + } + } finally { + // Unlink DACL dump regardless of success/failure in this span. + if (daclDumpPath !== null) { + await fs.unlink(daclDumpPath).catch(() => {}) + } + } + + // tempPath is now the committed file; no cleanup needed. + + // Best-effort: remove the now-empty staging directory. Self-staged + // writes only, and only this write's own directory: a per-write directory + // cannot be the one another concurrent write is still using. A failure must + // never un-commit a published file, so the removal swallows all errors. + if (stagingDir) { + await fs.rmdir(stagingDir).catch(() => {}) + } + } catch (originalError: unknown) { + // The backup is a copy, never a restore source: whether the failure happened before + // or after the commit rename, the copy is removed below so no stale duplicate of the + // previous content survives next to the target. + // Set when a backup copy this write made could not be removed; reported at the end of + // this catch so the staging cleanup above is not skipped for a cleanup failure. + let pendingBackupError: OrphanedBackupAfterFailedWriteError | null = null + if (backupPath && releaseBackupOnSuccess) { + // Nothing to restore: the backup is a copy, so the target still holds whatever + // the commit left there - before the commit that is the pre-write content, and + // after it the published content. Either way the copy has served its purpose + // and must not be left beside the target where no caller can find it. + const removalError = await _removeBackupWithRetry(backupPath) + if (removalError !== null) { + // The copy of the previous content is still on disk and only this function knew + // where. Reporting it is what keeps the original error the primary fact while + // leaving the leftover findable; swallowing the removal left both unreported. + // Constructed, not thrown yet: the staging cleanup below has to run first, so + // the leftover is reported once this catch has finished what it can do about the + // write's own mess. + pendingBackupError = new OrphanedBackupAfterFailedWriteError( + targetPath, + backupPath, + originalError, + removalError, + stagingCommitted, + ) + } + backupPath = null + } + if (!stagingCommitted) { + try { + await fs.unlink(tempPath).catch(() => {}) + } catch { + // cleanup failure is non-fatal + } + } + + // A failed self-staged write must not leave its staging directory behind. + // Only the directory this write created, and only after its temp file is + // gone, so the directory is empty and the removal stays best-effort. + if (stagingDir) { + await fs.rmdir(stagingDir).catch(() => {}) + } + + if (daclDumpPath !== null) { + await fs.unlink(daclDumpPath).catch(() => {}) + } + + if (pendingBackupError) { + // The write's own failure is still the primary fact - it travels on this error as + // originalError and as its cause - and the copy of the previous content now has a + // path a caller can act on instead of being unreported. + throw pendingBackupError + } + throw originalError + } +} diff --git a/src/services/mcp/McpHub.ts b/src/services/mcp/McpHub.ts index c973f35a03..50ae26ebb3 100644 --- a/src/services/mcp/McpHub.ts +++ b/src/services/mcp/McpHub.ts @@ -630,8 +630,9 @@ export class McpHub { } // Get project-level MCP configuration path - private async getProjectMcpPath(): Promise { - const workspacePath = this.providerRef.deref()?.cwd ?? getWorkspacePath() + private async getProjectMcpPath( + workspacePath: string | undefined = this.providerRef.deref()?.cwd ?? getWorkspacePath(), + ): Promise { const projectMcpDir = path.join(workspacePath, ".roo") const projectMcpPath = path.join(projectMcpDir, "mcp.json") @@ -643,6 +644,41 @@ export class McpHub { } } + /** + * The root a project-scoped MCP write has to stay inside. + * + * safeWriteJson resolves the publish target with realpath before staging beside it, so a + * repository that ships .roo/mcp.json as a symlink to a file OUTSIDE the workspace would + * have that outside file replaced as soon as the user edits a project MCP setting or + * allowlist. Passing the workspace root as confineTo makes that write fail closed instead. + * Global writes are deliberately unconstrained: they target the user's own settings + * directory, which is not under the workspace. + * + * DECISION AND LIMIT - these three call sites carry credentials (MCP server env and + * headers), so the limit of the control they pass is stated here rather than left to the + * option doc: confineTo decides twice from the resolved publish target and stops at its + * final component. If a workspace replaces an ANCESTOR directory - .roo, or the workspace + * directory itself - with a link after the last check, the credential write follows that + * link and can still land outside the workspace; see the confineTo doc in + * src/utils/safeWriteJson.ts for the two outcomes of that window. The control is kept + * anyway, not dropped, because the case a committed tree can actually plant is a link at + * the settings file itself, and that is the case this option does refuse. Closing the + * ancestor window needs a handle-relative no-follow publish, which this runtime does not + * offer, and the alternative reading - removing the control from the credential path - + * would give up the refusal that works today to close a window no unit can close here. + */ + private confineForMcpWrite( + source: "global" | "project", + // The root chosen by the same write: reading it twice lets a workspace refresh between the + // path lookup and this check reject a valid project write with a confinement error. + workspacePath: string | undefined = this.providerRef.deref()?.cwd ?? getWorkspacePath(), + ): string | undefined { + if (source !== "project") { + return undefined + } + return workspacePath + } + // Initialize project-level MCP servers private async initializeProjectMcpServers(): Promise { await this.initializeMcpServers("project") @@ -2038,10 +2074,12 @@ export class McpHub { configUpdate: Record, source: "global" | "project" = "global", ): Promise { - // Determine which config file to update + // Determine which config file to update. The write root is captured once and reused by + // the confinement check below, so a workspace refresh cannot split the two reads. let configPath: string + const writeRoot = source === "project" ? (this.providerRef.deref()?.cwd ?? getWorkspacePath()) : undefined if (source === "project") { - const projectMcpPath = await this.getProjectMcpPath() + const projectMcpPath = await this.getProjectMcpPath(writeRoot) if (!projectMcpPath) { throw new Error("Project MCP configuration file not found") } @@ -2099,7 +2137,10 @@ export class McpHub { } this.isProgrammaticUpdate = true try { - await safeWriteJson(configPath, updatedConfig, { prettyPrint: true }) + await safeWriteJson(configPath, updatedConfig, { + prettyPrint: true, + confineTo: this.confineForMcpWrite(source, writeRoot), + }) } finally { // Reset flag after watcher debounce period (non-blocking) this.flagResetTimer = setTimeout(() => { @@ -2143,10 +2184,12 @@ export class McpHub { // Determine config file based on server source const isProjectServer = serverSource === "project" let configPath: string + const writeRoot = + serverSource === "project" ? (this.providerRef.deref()?.cwd ?? getWorkspacePath()) : undefined if (isProjectServer) { // Get project MCP config path - const projectMcpPath = await this.getProjectMcpPath() + const projectMcpPath = await this.getProjectMcpPath(writeRoot) if (!projectMcpPath) { throw new Error("Project MCP configuration file not found") } @@ -2184,7 +2227,10 @@ export class McpHub { mcpServers: config.mcpServers, } - await safeWriteJson(configPath, updatedConfig, { prettyPrint: true }) + await safeWriteJson(configPath, updatedConfig, { + prettyPrint: true, + confineTo: this.confineForMcpWrite(serverSource, writeRoot), + }) // Update server connections with the correct source await this.updateServerConnections(config.mcpServers, serverSource) @@ -2342,9 +2388,10 @@ export class McpHub { // Determine the correct config path based on the source let configPath: string + const writeRoot = source === "project" ? (this.providerRef.deref()?.cwd ?? getWorkspacePath()) : undefined if (source === "project") { // Get project MCP config path - const projectMcpPath = await this.getProjectMcpPath() + const projectMcpPath = await this.getProjectMcpPath(writeRoot) if (!projectMcpPath) { throw new Error("Project MCP configuration file not found") } @@ -2393,7 +2440,10 @@ export class McpHub { } this.isProgrammaticUpdate = true try { - await safeWriteJson(normalizedPath, config, { prettyPrint: true }) + await safeWriteJson(normalizedPath, config, { + prettyPrint: true, + confineTo: this.confineForMcpWrite(source, writeRoot), + }) } finally { // Reset flag after watcher debounce period (non-blocking) this.flagResetTimer = setTimeout(() => { diff --git a/src/services/mcp/__tests__/McpHub.spec.ts b/src/services/mcp/__tests__/McpHub.spec.ts index 35ff10d64b..b6aacddc94 100644 --- a/src/services/mcp/__tests__/McpHub.spec.ts +++ b/src/services/mcp/__tests__/McpHub.spec.ts @@ -3,7 +3,8 @@ import * as path from "path" import type { Mock } from "vitest" import type { ExtensionContext, Uri } from "vscode" -import type { Client } from "@modelcontextprotocol/sdk/client/index.js" +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js" +import { Client } from "@modelcontextprotocol/sdk/client/index.js" import type { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js" import type { ClineProvider } from "../../../core/webview/ClineProvider" @@ -35,6 +36,7 @@ vi.mock("fs/promises", () => { }) // Import safeWriteJson to use in mocks +import { safeWriteJson } from "../../../utils/safeWriteJson" // Mock safeWriteJson vi.mock("../../../utils/safeWriteJson", () => ({ @@ -158,6 +160,22 @@ describe("McpHub", () => { let mcpHub: McpHubType let mockProvider: Partial + // A fully typed connection double: the SDK constructors are mocked at the top of the + // file, so no cast is needed to build a connected connection here. Shared by the + // write-confinement tests for every project-capable entry point. + const connectionFor = (source: "global" | "project"): ConnectedMcpConnection => ({ + type: "connected", + server: { + name: "test-server", + config: JSON.stringify({ type: "stdio", command: "node", args: ["test.js"], alwaysAllow: [] }), + status: "connected", + source, + errorHistory: [], + }, + client: new Client({ name: "test-client", version: "1.0.0" }), + transport: new StdioClientTransport({ command: "node", args: ["test.js"] }), + }) + // Store original console methods const originalConsoleError = console.error const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform") @@ -1205,7 +1223,130 @@ describe("McpHub", () => { }) }) + describe("project-scoped write confinement at every call site", () => { + // safeWriteJson resolves the publish target with realpath before staging beside it, so + // a project .roo/mcp.json that links outside the workspace would be written THROUGH the + // link unless the caller declares the workspace as the confinement root. Every + // project-capable entry point has to pass it. A lower-level safeWriteJson test cannot + // see a missing MCP argument (the writer is mocked here), so each call site is pinned. + const projectConfigJson = JSON.stringify({ + mcpServers: { "test-server": { type: "stdio", command: "node", args: ["test.js"], timeout: 60 } }, + }) + + it("confines a project-scoped timeout write to the workspace root", async () => { + Object.defineProperty(mockProvider, "cwd", { value: "/mock/workspace", configurable: true }) + vi.mocked(fs.readFile).mockResolvedValueOnce(projectConfigJson) + mcpHub.connections = [connectionFor("project")] + + await mcpHub.updateServerTimeout("test-server", 120) + + const write = vi.mocked(safeWriteJson).mock.calls.find((call) => String(call[0]).includes(".roo")) + expect(write).toBeDefined() + expect(write![2]).toEqual(expect.objectContaining({ confineTo: "/mock/workspace" })) + }) + + it("leaves a global-scoped timeout write unconstrained", async () => { + Object.defineProperty(mockProvider, "cwd", { value: "/mock/workspace", configurable: true }) + // The global path creates the default settings file when it is missing, and that + // write's merge callback reads the file; updateServerConfig then reads it too. + vi.mocked(fs.readFile).mockResolvedValueOnce(projectConfigJson) + vi.mocked(fs.readFile).mockResolvedValueOnce(projectConfigJson) + mcpHub.connections = [connectionFor("global")] + + await mcpHub.updateServerTimeout("test-server", 120) + + const writes = vi + .mocked(safeWriteJson) + .mock.calls.filter((call) => String(call[0]).includes("mcp_settings")) + expect(writes.length).toBeGreaterThan(0) + for (const write of writes) { + expect(write[2]?.confineTo).toBeUndefined() + } + }) + + it("confines a project-scoped server deletion to the workspace root", async () => { + Object.defineProperty(mockProvider, "cwd", { value: "/mock/workspace", configurable: true }) + vi.mocked(fs.readFile).mockResolvedValueOnce(projectConfigJson) + mcpHub.connections = [connectionFor("project")] + + await mcpHub.deleteServer("test-server", "project") + + const write = vi.mocked(safeWriteJson).mock.calls.find((call) => String(call[0]).includes(".roo")) + expect(write).toBeDefined() + expect(write![2]).toEqual(expect.objectContaining({ confineTo: "/mock/workspace" })) + }) + + it("leaves a global-scoped server deletion unconstrained", async () => { + Object.defineProperty(mockProvider, "cwd", { value: "/mock/workspace", configurable: true }) + vi.mocked(fs.readFile).mockResolvedValueOnce(projectConfigJson) + vi.mocked(fs.readFile).mockResolvedValueOnce(projectConfigJson) + mcpHub.connections = [connectionFor("global")] + + await mcpHub.deleteServer("test-server", "global") + + const writes = vi + .mocked(safeWriteJson) + .mock.calls.filter((call) => String(call[0]).includes("mcp_settings")) + expect(writes.length).toBeGreaterThan(0) + for (const write of writes) { + expect(write[2]?.confineTo).toBeUndefined() + } + }) + }) + describe("toggleToolAlwaysAllow", () => { + const projectConnection = (source: "global" | "project" = "project"): ConnectedMcpConnection => + connectionFor(source) + + it("confines a project-scoped allowlist write to the workspace root", async () => { + // A repository can ship .roo/mcp.json as a symlink to a file outside the workspace. + // safeWriteJson resolves the publish target before staging, so without confinement an + // allowlist edit would replace that outside file. The workspace root has to be handed + // over as confineTo so the write fails closed instead. + // cwd is a read-only getter on ClineProvider, so the test installs the value. + Object.defineProperty(mockProvider, "cwd", { value: "/mock/workspace", configurable: true }) + vi.mocked(fs.readFile).mockResolvedValueOnce( + JSON.stringify({ + mcpServers: { + "test-server": { type: "stdio", command: "node", args: ["test.js"], alwaysAllow: [] }, + }, + }), + ) + mcpHub.connections = [projectConnection()] + + await mcpHub.toggleToolAlwaysAllow("test-server", "project", "new-tool", true) + + const write = vi.mocked(safeWriteJson).mock.calls.find((call) => String(call[0]).includes("mcp.json")) + expect(write).toBeDefined() + expect(write![2]).toEqual(expect.objectContaining({ confineTo: "/mock/workspace" })) + }) + + it("leaves a global-scoped allowlist write unconstrained", async () => { + // Global settings live in the user's own settings directory, which is not under the + // workspace; confining them would break every global edit. + Object.defineProperty(mockProvider, "cwd", { value: "/mock/workspace", configurable: true }) + mcpHub.connections = [projectConnection("global")] + + await mcpHub.toggleToolAlwaysAllow("test-server", "global", "another-tool", true) + + // Name the exact call instead of picking any match: a find on the substring + // "mcp" returns the FIRST mcp-named write, which need not be the allowlist + // write - the default-creation write getMcpSettingsFilePath makes when the + // settings file is missing (McpHub.ts:513) also matches, and it never passes + // confineTo, so the assertion could judge that write and stay green while a + // confinement root on the real allowlist write went unnoticed. Check every + // write to the settings file, as the timeout and delete tests above do. + const writes = vi + .mocked(safeWriteJson) + .mock.calls.filter((call) => String(call[0]).endsWith("mcp_settings.json")) + expect(writes.length).toBeGreaterThan(0) + // undefined confineTo is the unconstrained case: safeWriteJson only checks the path + // when a confinement root is supplied. + for (const write of writes) { + expect(write[2]?.confineTo).toBeUndefined() + } + }) + it("should add tool to always allow list when enabling", async () => { const mockConfig = { mcpServers: { diff --git a/src/utils/__tests__/fileLock.canonicalKey.spec.ts b/src/utils/__tests__/fileLock.canonicalKey.spec.ts new file mode 100644 index 0000000000..1dab157057 --- /dev/null +++ b/src/utils/__tests__/fileLock.canonicalKey.spec.ts @@ -0,0 +1,67 @@ +// npx vitest run utils/__tests__/fileLock.canonicalKey.spec.ts + +import path from "path" +import type { BigIntStats } from "fs" +import * as fs from "fs/promises" +import * as lockfile from "proper-lockfile" +import { withFileLock } from "../fileLock" +import { resolveLockKey } from "../../services/file-safety/safeWriteText" + +vi.mock("proper-lockfile", () => ({ + lock: vi.fn(async () => async () => {}), + unlock: vi.fn(async () => {}), +})) + +vi.mock("fs/promises", async () => { + const actual = await vi.importActual("fs/promises") + return { ...actual, realpath: vi.fn(), lstat: vi.fn(), readlink: vi.fn() } +}) + +const mockedRealpath = vi.mocked(fs.realpath) +const mockedLstat = vi.mocked(fs.lstat) +const mockedReadlink = vi.mocked(fs.readlink) +const mockedLock = vi.mocked(lockfile.lock) + +const dir = path.resolve(path.join(path.sep + "work", "history")) +const referent = path.join(dir, "item.json") +const alias = path.join(dir, "alias.json") + +beforeEach(() => { + mockedRealpath.mockReset() + mockedLstat.mockReset() + mockedReadlink.mockReset() + mockedLock.mockReset() + // alias.json is a symlink to item.json; everything else resolves to itself. + mockedRealpath.mockImplementation(async (target) => (target === alias ? referent : String(target))) + mockedLstat.mockImplementation(async () => ({ isSymbolicLink: () => false }) as unknown as BigIntStats) + mockedReadlink.mockRejectedValue(Object.assign(new Error("not a link"), { code: "EINVAL" })) +}) + +describe("withFileLock lock-key canonicalization", () => { + it("locks the canonical referent that safeWriteJson locks, not the raw alias", async () => { + // The compound-atomicity contract of task-history deletion is that an + // unlink under this helper and a safeWriteJson read-modify-write on the + // same file serialize. That holds only while both compute ONE key: + // safeWriteJson locks resolveLockKey(target), so withFileLock must too. + // Locking the raw alias here would watch a different lock file and let + // the deletion interleave with the merge write. + await withFileLock(alias, async () => undefined) + + expect(mockedLock).toHaveBeenCalledTimes(1) + expect(mockedLock.mock.calls[0][0]).toBe(referent) + // The shared-key contract stated directly: whatever safeWriteJson would + // lock for the same path is exactly what this helper locked. + expect(mockedLock.mock.calls[0][0]).toBe(await resolveLockKey(alias)) + }) + + it("hands the operation the caller's own path so its unlink keeps alias semantics", async () => { + // unlink(alias) removes the link; unlink(referent) removes the target + // file. Deletion must act on the path the caller named, even though the + // lock is taken on the canonical key. + const seen: string[] = [] + await withFileLock(alias, async (absoluteFilePath) => { + seen.push(absoluteFilePath) + }) + expect(seen).toEqual([alias]) + }) +}) diff --git a/src/utils/__tests__/fileLock.spec.ts b/src/utils/__tests__/fileLock.spec.ts new file mode 100644 index 0000000000..0c2bf8c03e --- /dev/null +++ b/src/utils/__tests__/fileLock.spec.ts @@ -0,0 +1,308 @@ +// npx vitest run utils/__tests__/fileLock.spec.ts + +import * as path from "path" + +import * as fsPromises from "fs/promises" + +import * as lockfile from "proper-lockfile" + +import { acquireFileLock, withFileLock } from "../fileLock" + +vi.mock("fs/promises", () => ({ + realpath: vi.fn(async (target: unknown) => { + const asString = String(target) + // A path that does not exist yet reports ENOENT, as the real fs does. + if (asString.includes("missing")) { + throw Object.assign(new Error("ENOENT"), { code: "ENOENT" }) + } + return asString.replace("aliasDir", "realDir") + }), + // A non-link rejects readlink, exactly like the real fs; the link tests + // override this per path. + readlink: vi.fn(async () => { + throw Object.assign(new Error("EINVAL"), { code: "EINVAL" }) + }), +})) + +vi.mock("proper-lockfile", () => ({ + lock: vi.fn(async () => async () => {}), +})) + +/** + * proper-lockfile derives its lock file from the path it is handed, and this module + * turns off the library's own realpath step because the file may not exist yet. Without + * a canonical lock key, a writer that reaches a file through a symlinked directory and a + * deleter that reaches the same file lexically take DIFFERENT locks and silently lose + * updates against each other - the shape a task file under a symlinked task directory + * has against a task-history delete. + */ +const STORE = path.resolve("/tmp/store") + +describe("fileLock - canonical lock keys", () => { + beforeEach(() => { + vi.mocked(lockfile.lock).mockClear() + }) + + test("locks the referent when the path runs through a symlinked directory", async () => { + const releaseLock = await acquireFileLock(path.join(STORE, "aliasDir", "task.json")) + + expect(lockfile.lock).toHaveBeenCalledWith( + path.join(STORE, "realDir", "task.json"), + expect.objectContaining({ realpath: false }), + ) + + await releaseLock() + }) + + test("locks the referent but hands the operation the caller's own path", async () => { + // The mutex key is canonical; the path the caller works on is left alone. On Windows + // realpath can answer with the 8.3 short form, and rewriting the path a caller + // unlinks or compares would change behavior for every caller for no mutex gain. + const callerPath = path.join(STORE, "aliasDir", "task.json") + const seen: string[] = [] + await withFileLock(callerPath, async (absoluteFilePath) => { + seen.push(absoluteFilePath) + }) + + expect(seen).toEqual([callerPath]) + expect(lockfile.lock).toHaveBeenCalledWith( + path.join(STORE, "realDir", "task.json"), + expect.objectContaining({ realpath: false }), + ) + }) + + test("propagates a realpath failure that is not ENOENT instead of locking a guessed key", async () => { + // A permission failure says nothing about the path's identity, which is exactly the + // problem: the caller spelling is then a key we cannot prove anyone else is taking, and a + // writer that reaches the same file through the referent holds a DIFFERENT lock. The stack + // already refuses to guess in safeWriteText.resolveLockKey for the same reason; the lock + // path has to refuse too rather than let two writers run at once. + vi.mocked(fsPromises.realpath).mockRejectedValueOnce( + Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }), + ) + const callerPath = path.join(STORE, "aliasDir", "task.json") + + await expect( + withFileLock(callerPath, async (absoluteFilePath) => { + expect(absoluteFilePath).toBe(callerPath) + }), + ).rejects.toMatchObject({ code: "EACCES" }) + + // Nothing was locked, so nothing ran under a key no peer was contending for. + expect(lockfile.lock).not.toHaveBeenCalled() + }) + + // The rule keys off the codes that mean "nothing is here yet". An error that carries no code + // at all is not evidence of absence, so it propagates on the same rule as EACCES. + test("propagates a realpath failure that carries no error code", async () => { + vi.mocked(fsPromises.realpath).mockRejectedValueOnce(new Error("unknown failure")) + const callerPath = path.join(STORE, "aliasDir", "task.json") + + await expect( + withFileLock(callerPath, async (absoluteFilePath) => { + expect(absoluteFilePath).toBe(callerPath) + }), + ).rejects.toThrow("unknown failure") + + expect(lockfile.lock).not.toHaveBeenCalled() + }) + + // The two rows above reach the lock through withFileLock, which calls canonicalLockPath and + // _lockCanonicalKey directly and never passes through acquireFileLock. A fallback added only to + // that exported entry point - canonicalize, and on any failure lock the caller's own spelling - + // would leave both of them green while a direct caller (safeWriteJson, task-history deletion) + // started taking a lock no peer was contending for. Same rejections, direct entry point. + test("propagates an EACCES realpath failure through the acquireFileLock entry point", async () => { + vi.mocked(fsPromises.realpath).mockRejectedValueOnce( + Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }), + ) + const callerPath = path.join(STORE, "aliasDir", "task.json") + + await expect(acquireFileLock(callerPath)).rejects.toMatchObject({ code: "EACCES" }) + + // Nothing was locked, so nothing ran under a key no peer was contending for. + expect(lockfile.lock).not.toHaveBeenCalled() + }) // end acquireFileLock EACCES row + + test("propagates a code-less realpath failure through the acquireFileLock entry point", async () => { + vi.mocked(fsPromises.realpath).mockRejectedValueOnce(new Error("unknown failure")) + const callerPath = path.join(STORE, "aliasDir", "task.json") + + await expect(acquireFileLock(callerPath)).rejects.toThrow("unknown failure") + + expect(lockfile.lock).not.toHaveBeenCalled() + }) // end acquireFileLock code-less row + + test("canonicalizes the nearest existing ancestor when the file does not exist yet", async () => { + // The file and its parent are absent, so realpath reports ENOENT for them; the deepest + // existing ancestor is resolved and the missing components are re-appended. + const seen: string[] = [] + await withFileLock(path.join(STORE, "aliasDir", "missing", "new.json"), async (absoluteFilePath) => { + seen.push(absoluteFilePath) + }) + + expect(seen).toEqual([path.join(STORE, "aliasDir", "missing", "new.json")]) + expect(lockfile.lock).toHaveBeenCalledWith( + path.join(STORE, "realDir", "missing", "new.json"), + expect.objectContaining({ realpath: false }), + ) + }) +}) + +test("locks the canonicalized referent of a file symlink whose target is temporarily absent", async () => { + // A backup-mode commit renames the referent away and back. During that window the + // link is dangling, realpath fails, and a naive fallback re-appends the LINK's + // basename onto the canonical parent - a different key from the one safeWriteJson + // holds through resolveLockKey, so the two writers stop excluding each other. + // The referent sits under aliasDir and under a component the realpath double reports as + // absent, so this row actually walks the missing-referent path: realpath of the link and of + // the referent both report ENOENT, and the answer has to come back as the deepest + // canonicalized ancestor plus the components that are missing - not the link's own name. + const aliasDir = path.join(STORE, "aliasDir") + const linkPath = path.join(aliasDir, "link.json") + const referent = path.join(aliasDir, "missingReferent.json") + vi.mocked(fsPromises.readlink).mockImplementation(async (p: unknown) => { + if (String(p) === linkPath) return referent + throw Object.assign(new Error("EINVAL"), { code: "EINVAL" }) + }) + + const releaseLock = await acquireFileLock(linkPath) + + expect(lockfile.lock).toHaveBeenCalledWith( + path.join(STORE, "realDir", "missingReferent.json"), + expect.objectContaining({ realpath: false }), + ) + + await releaseLock() +}) +test("terminates on a three-link cycle instead of recursing forever", async () => { + // a -> b -> c -> a: the cycle length does not divide the per-frame walk bound, + // so a recursion that restarts its hop budget on every frame never terminates - + // each frame walks 8 hops, lands on a different cycle member, and recurses. + // resolveLockKey hands a cycle member to withFileLock, so an unbounded + // canonicalLockPath hangs every guarded writer on the lock path, not just the + // walker. The readlink mock yields to a timer so a regression fails on the + // test timeout instead of starving the event loop. + // Top-level test: clear the shared doubles so the counts below are this test's own. + vi.mocked(lockfile.lock).mockClear() + vi.mocked(fsPromises.readlink).mockClear() + vi.mocked(fsPromises.realpath).mockClear() + + const a = path.join(STORE, "cyc", "a.json") + const b = path.join(STORE, "cyc", "b.json") + const c = path.join(STORE, "cyc", "c.json") + const cycle: Record = { [a]: b, [b]: c, [c]: a } + vi.mocked(fsPromises.readlink).mockImplementation(async (target: unknown) => { + await new Promise((resolve) => setTimeout(resolve, 0)) + const referent = cycle[String(target)] + if (referent === undefined) throw Object.assign(new Error("EINVAL"), { code: "EINVAL" }) + return referent + }) + vi.mocked(fsPromises.realpath).mockImplementation(async () => { + throw Object.assign(new Error("ENOENT"), { code: "ENOENT" }) + }) + + const releaseLock = await acquireFileLock(a) + + // Terminated with exactly one lock acquisition on a cycle member, and the + // total hop budget held across all frames. + expect(lockfile.lock).toHaveBeenCalledTimes(1) + expect(vi.mocked(fsPromises.readlink).mock.calls.length).toBeLessThanOrEqual(64) + + await releaseLock() +}) + +test("resolves a relative link target from the canonical parent, not from the caller's spelling", async () => { + // A link under a symlinked directory that points "../referent.json": the referent is a + // sibling of the REAL parent, so joining the referent lexically onto aliasDir names a + // different file. The writer through the alias would then hold a lock the writer through + // the referent never contends for. The mock canonicalizes aliasDir to a directory at a + // different depth, so the two answers are distinguishable instead of both landing on the + // same store/referent.json. + vi.mocked(lockfile.lock).mockClear() + vi.mocked(fsPromises.readlink).mockClear() + vi.mocked(fsPromises.realpath).mockClear() + const aliasParent = path.join(STORE, "aliasDir") + const linkPath = path.join(aliasParent, "link.json") + vi.mocked(fsPromises.readlink).mockImplementation(async (p: unknown) => { + if (String(p) === linkPath) return "../referent.json" + throw Object.assign(new Error("EINVAL"), { code: "EINVAL" }) + }) + vi.mocked(fsPromises.realpath).mockImplementation(async (target: unknown) => { + const asString = String(target) + if (asString === aliasParent) return path.resolve("/tmp/outer/real") + return asString + }) + + const releaseLock = await acquireFileLock(linkPath) + + expect(lockfile.lock).toHaveBeenCalledWith( + path.resolve("/tmp/outer/referent.json"), + expect.objectContaining({ realpath: false }), + ) + + await releaseLock() +}) + +test("retakes the lock when the canonical key moves while the callback waits to run", async () => { + // A directory component can be swapped while this call waits for the lock, leaving it + // holding the OLD canonical key while a peer reaching the file through the NEW one takes a + // different lock. withFileLock re-derives the key before running the callback and, on a + // change, releases, retakes for the current key, and only then runs. The double below flips + // the canonical parent inside the first acquisition, which is that swap. + vi.mocked(lockfile.lock).mockClear() + vi.mocked(fsPromises.readlink).mockClear() + vi.mocked(fsPromises.realpath).mockClear() + const aliasPath = path.join(STORE, "aliasDir", "task.json") + let resolvedDir = "realDirOne" + let acquisitions = 0 + vi.mocked(fsPromises.realpath).mockImplementation(async (target: unknown) => + String(target).replace("aliasDir", resolvedDir), + ) + // Each acquisition and the one release are logged into ONE list around the same 30 ms + // hold, and the callback logs into it too, so the row can pin one order end to end instead of + // only the keys and a callback count. The release double throws away the second release on + // purpose: only the first acquisition's lock is still held when the retarget happens, and the + // row is about the order, not about releasing a lock the helper already dropped. + const events: string[] = [] + vi.mocked(lockfile.lock).mockImplementation(async () => { + const acquiredAs = ++acquisitions + events.push("acquire:" + acquiredAs + ":started") + if (acquiredAs === 1) resolvedDir = "realDirTwo" + await new Promise((resolve) => setTimeout(resolve, 30)) + events.push("acquire:" + acquiredAs + ":completed") + return async () => { + if (acquiredAs !== 1) { + return + } + events.push("release:started") + await new Promise((resolve) => setTimeout(resolve, 30)) + events.push("release:completed") + } + }) + + const seen: string[] = [] + await withFileLock(aliasPath, async (absoluteFilePath) => { + seen.push(absoluteFilePath) + events.push("callback") + }) + + const keys = vi.mocked(lockfile.lock).mock.calls.map((call) => String(call[0])) + expect(keys).toEqual([path.join(STORE, "realDirOne", "task.json"), path.join(STORE, "realDirTwo", "task.json")]) + // The callback still receives the caller's own spelling, and it ran exactly once, after the + // retarget - not under the key that had already become stale. + expect(seen).toEqual([aliasPath]) + // The order is the assertion this row was raised about. The stale key's release has to finish + // before the replacement is asked for, and the callback has to run only once the replacement is + // held: either half regressing on its own used to pass here with the key list and the callback + // count both unchanged, because the old double logged nothing. + expect(events).toEqual([ + "acquire:1:started", + "acquire:1:completed", + "release:started", + "release:completed", + "acquire:2:started", + "acquire:2:completed", + "callback", + ]) +}) diff --git a/src/utils/__tests__/jsonFileRecovery.test.ts b/src/utils/__tests__/jsonFileRecovery.test.ts index ce33e739b4..1db0abf264 100644 --- a/src/utils/__tests__/jsonFileRecovery.test.ts +++ b/src/utils/__tests__/jsonFileRecovery.test.ts @@ -42,8 +42,12 @@ describe("reader recovery", () => { } vi.mocked(fs.readdir).mockRejectedValueOnce(error) } - await expect(readFileWithMissingRetry(target)).rejects.toBe(error) + // A recovery that rejects is traced by jsonFileRecovery with its own code and then + // counted as nothing recovered, so the reader hands back the ENOENT its callers classify by + // error code. The two trace assertions are where that recovery failure is reported. + await expect(readFileWithMissingRetry(target)).rejects.toMatchObject({ code: "ENOENT" }) expect(sink).toHaveBeenCalledWith(expect.stringContaining('"result":"failed"')) + expect(sink).toHaveBeenCalledWith(expect.stringContaining('"detail":"EIO"')) expect(JSON.parse(await fs.readFile(backup, "utf8"))).toEqual({ committed: true }) await expect(fs.readFile(target)).rejects.toMatchObject({ code: "ENOENT" }) expect(JSON.parse(await readFileWithMissingRetry(target))).toEqual({ committed: true }) diff --git a/src/utils/__tests__/safeWriteJson.interruption.test.ts b/src/utils/__tests__/safeWriteJson.interruption.test.ts index c9c5993f84..45fa6a735e 100644 --- a/src/utils/__tests__/safeWriteJson.interruption.test.ts +++ b/src/utils/__tests__/safeWriteJson.interruption.test.ts @@ -32,12 +32,44 @@ const targetPath = path.resolve(process.env.INTERRUPTION_TARGET_PATH) const fsPromises = require("fs/promises") const actualRename = fsPromises.rename +// Identity, not spelling. The writer renames to the publish target it resolved through +// symlinks, and node's async fs.realpath expands an NTFS 8.3 alias, so on a runner whose temp +// path is reported as an alias (the normal windows-latest condition: the profile is RUNNER~1 +// there) the parent's authorized spelling and the writer's rename destination are different +// strings for one file. Text equality here never fires, every case prints WRITE_COMPLETED, and +// the injection silently stops being an injection. Decide what the destination IS: same name, +// and the same directory by dev+ino. The basenames under test are unique inside the storage +// directory, so the pair cannot land on another file. +const targetBase = path.basename(targetPath) +function sameTargetAsAuthorized(candidate) { + if (path.basename(String(candidate)) !== targetBase) { + return false + } + const resolved = path.resolve(String(candidate)) + if (resolved === targetPath) { + return true + } + let candidateDir = null + let authorizedDir = null + try { + candidateDir = fs.statSync(path.dirname(resolved), { bigint: true }) + } catch { + return false + } + try { + authorizedDir = fs.statSync(path.dirname(targetPath), { bigint: true }) + } catch { + return false + } + return candidateDir.dev === authorizedDir.dev && candidateDir.ino === authorizedDir.ino +} + // Fault injection: hard-kill before the replacement lands. Any rename -// whose destination is the canonical path is the commit step, whatever +// whose destination is the publish target is the commit step, whatever // replacement protocol the writer uses; exit before performing it. let commitAttempts = 0 fsPromises.rename = async function interruptionRename(oldPath, newPath) { - if (path.resolve(String(newPath)) === targetPath) { + if (sameTargetAsAuthorized(newPath)) { commitAttempts++ if (process.env.INTERRUPTION_MODE === "fallback" && commitAttempts === 1) { return Promise.reject(Object.assign(new Error("Injected EPERM"), { code: "EPERM" })) diff --git a/src/utils/__tests__/safeWriteJson.lockKey.spec.ts b/src/utils/__tests__/safeWriteJson.lockKey.spec.ts new file mode 100644 index 0000000000..3033fb237c --- /dev/null +++ b/src/utils/__tests__/safeWriteJson.lockKey.spec.ts @@ -0,0 +1,201 @@ +// npx vitest run utils/__tests__/safeWriteJson.lockKey.spec.ts + +import * as os from "os" +import path from "path" +import type { BigIntStats } from "fs" +import * as fs from "fs/promises" +import { acquireFileLock } from "../fileLock" +import { safeWriteJson } from "../safeWriteJson" +import { resolveLockKey } from "../../services/file-safety/safeWriteText" + +vi.mock("../fileLock", () => ({ + acquireFileLock: vi.fn(async () => async () => {}), +})) + +vi.mock("fs/promises", async () => { + const actual = await vi.importActual("fs/promises") + return { ...actual, realpath: vi.fn(), lstat: vi.fn(), readlink: vi.fn() } +}) + +const mockedRealpath = vi.mocked(fs.realpath) +const mockedLstat = vi.mocked(fs.lstat) +const mockedReadlink = vi.mocked(fs.readlink) +const mockedAcquireFileLock = vi.mocked(acquireFileLock) + +const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + +// Each test creates a real temp directory so the real fs calls still work. +// doubles between tests so an implementation from one test cannot carry over. +const createdDirs: string[] = [] +async function makeDir(prefix: string): Promise { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix)) + createdDirs.push(dir) + return dir +} + +beforeEach(() => { + mockedRealpath.mockReset() + mockedLstat.mockReset() + mockedReadlink.mockReset() + mockedAcquireFileLock.mockReset() +}) + +afterEach(async () => { + for (const dir of createdDirs) { + await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined) + } + createdDirs.length = 0 +}) + +// Only isSymbolicLink() is consulted by the guard, so the double carries just +// that method. The mocks reject asynchronously: a synchronous throw would bypass +// resolvePublishTarget's catch and skip the ENOENT/symlink branch under test. +const symlinkStat = (target: unknown) => + ({ + isSymbolicLink: () => target === currentLink, + // The staging-path check in safeWriteText also asks whether the path is a + // regular file, so the double carries that predicate as well. + isFile: () => target !== currentLink, + }) as unknown as BigIntStats +let currentLink = "" + +describe("safeWriteJson lock key under a peer commit", () => { + it("waits for the peer instead of rejecting, and locks the referent", async () => { + const order: string[] = [] + const dir = await makeDir("lockkey-") + const referent = path.join(dir, "history_item.json") + currentLink = path.join(dir, "link.json") + + // The peer writer has renamed the referent away and has not committed yet, + // so the first resolution fails with ENOENT while lstat still reports a + // symbolic link. A strict resolve here rejects the caller before it can ever + // queue behind the peer, and the caller's delta write is lost. + mockedRealpath + .mockImplementationOnce(async () => { + order.push("resolve-failed") + throw enoent + }) + .mockImplementation(async (target) => { + order.push("resolve") + // The second call happens under the lock, where the peer has committed. + return target === currentLink ? referent : String(target) + }) + mockedLstat.mockImplementation(async (target) => { + order.push("lstat") + return symlinkStat(target) + }) + mockedReadlink.mockImplementation(async (target) => + target === currentLink ? referent : Promise.reject(new Error("not a link")), + ) + mockedAcquireFileLock.mockImplementation(async () => { + order.push("lock") + return async () => {} + }) + + await safeWriteJson(currentLink, { id: "task-1" }) + + // The lock key is the key every other writer to this file uses, so the caller + // queued behind the peer instead of failing before the lock. + expect(mockedAcquireFileLock).toHaveBeenCalledWith(referent) + // The extra resolves are the post-lock passes: the publish target is re-resolved, + // the lock key is re-derived, and every derivation canonicalizes through realpath, + // including the final stability check. All of them run after the lock was taken, so + // they do not change the lock the caller queued behind. The two trailing lstat + // calls belonged to the delegation flow's staging-path checks; the replacement + // protocol stages the temp itself and checks no identity beside it, so they are + // gone with the delegation. + expect(order).toEqual([ + "resolve-failed", + "lstat", + "resolve", + "resolve", + "lock", + "resolve", + "resolve", + "resolve", + "resolve", + "resolve", + ]) + expect(JSON.parse(await fs.readFile(referent, "utf8"))).toEqual({ id: "task-1" }) + }) + + it("releases the lock when the resolution under the lock rejects", async () => { + const order: string[] = [] + let released = false + const dir = await makeDir("lockkey-") + const referent = path.join(dir, "history_item.json") + currentLink = path.join(dir, "link.json") + + // A real dangling link: the walk tolerates it so the caller can queue behind + // the peer, but once the lock is held the strict rejection still applies. A + // rejection outside the protected block would leave the lock held until the + // stale timeout for every other writer to the same file. + mockedRealpath.mockImplementation(async () => { + throw enoent + }) + mockedLstat.mockImplementation(async (target) => { + order.push("lstat") + return symlinkStat(target) + }) + mockedReadlink.mockImplementation(async (target) => + target === currentLink ? referent : Promise.reject(new Error("not a link")), + ) + mockedAcquireFileLock.mockImplementation(async () => { + order.push("lock") + return async () => { + order.push("release") + released = true + } + }) + + await expect(safeWriteJson(currentLink, { id: "task-1" })).rejects.toThrow(enoent) + expect(released).toBe(true) + // The strict rejection is reached through the ENOENT + symlink branch, not + // through a synchronous throw that skips it. + expect(order).toEqual(["lstat", "lock", "lstat", "release"]) + }) + + it("canonicalizes the parent directory when the file itself is not there yet", async () => { + // fs.realpath canonicalizes every component, including a symlinked ancestor + // directory or a Windows 8.3 short name. If the fallback returns the alias + // directory, the key depends on whether the file exists at the moment the key + // is computed, and a writer that resolved the canonical directory takes a + // different lock for the same file. + const aliasDir = path.join(os.tmpdir(), "alias-dir") + const canonicalDir = path.join(os.tmpdir(), "canonical-dir") + const file = path.join(aliasDir, "history_item.json") + mockedRealpath.mockImplementation(async (target) => { + if (target === file) throw enoent + return canonicalDir + }) + mockedLstat.mockImplementation( + async () => ({ isSymbolicLink: () => false, isFile: () => true }) as unknown as BigIntStats, + ) + + expect(await resolveLockKey(file)).toBe(path.join(canonicalDir, "history_item.json")) + }) +}) + +it("does not log a cleanup error when the safety net finds the temp file already gone", async () => { + // safeWriteText removes its own temp file on failure, so the safety net in + // safeWriteJson normally finds it gone. That is the expected outcome, not a + // second failure, and it must not be logged as one. + const dir = await makeDir("cleanup-") + const target = path.join(dir, "history_item.json") + currentLink = "" + mockedRealpath.mockImplementation(async (t) => String(t)) + mockedLstat.mockImplementation(async (t) => symlinkStat(t)) + + const renameSpy = vi.spyOn(fs, "rename").mockRejectedValue(new Error("commit rename failed")) + const unlinkSpy = vi.spyOn(fs, "unlink").mockRejectedValue(enoent) + const consoleError = vi.spyOn(console, "error").mockImplementation(() => {}) + + await expect(safeWriteJson(target, { id: "task-1" })).rejects.toThrow("commit rename failed") + + // Only the original failure is reported. + expect(consoleError).toHaveBeenCalledTimes(1) + + renameSpy.mockRestore() + unlinkSpy.mockRestore() + consoleError.mockRestore() +}) diff --git a/src/utils/__tests__/safeWriteJson.test.ts b/src/utils/__tests__/safeWriteJson.test.ts index 30ac500212..4a9b51ed28 100644 --- a/src/utils/__tests__/safeWriteJson.test.ts +++ b/src/utils/__tests__/safeWriteJson.test.ts @@ -3,7 +3,7 @@ import { Writable } from "stream" import * as path from "path" import * as os from "os" -import { safeWriteJson } from "../safeWriteJson" +import { ConfinedPathEscapeError, safeWriteJson, undoEscapedPublish } from "../safeWriteJson" // Capture actual implementations before the vi.mock factory runs, // so they are never wrapped by vi.fn() — avoids infinite recursion when @@ -28,6 +28,7 @@ vi.mock("fs/promises", async () => { unlink: vi.fn(actual.unlink), access: vi.fn(actual.access), stat: vi.fn(actual.stat), + chmod: vi.fn(actual.chmod), open: vi.fn(actual.open), mkdtemp: vi.fn(actual.mkdtemp), rm: vi.fn(actual.rm), @@ -659,22 +660,44 @@ describe("safeWriteJson", () => { await fs.writeFile(unreadableBackup, JSON.stringify({ stale: true })) await fs.writeFile(readableBackup, JSON.stringify({ committed: true })) const actual = await vi.importActual("fs/promises") + // The injection is keyed on the leftover's inode, not on the spelling of its path: + // the writer stats the canonical form of the same file, which realpath can spell + // differently from os.tmpdir() on the machine running the test. Production cannot tell + // the two spellings apart - they are one file - so the double matches the inode. + const injectedInode = await actual.stat(unreadableBackup) + const isInjectedInode = async (candidate: Parameters[0]) => { + try { + const inode = await actual.stat(candidate) + return inode.dev === injectedInode.dev && inode.ino === injectedInode.ino + } catch { + return false // a candidate that cannot be stat-ed is not the injected leftover + } + } + // The double is installed for this test only. vi.restoreAllMocks() in afterEach does not + // clear implementations set on the fs/promises factory mocks, and the operating system + // recycles inodes, so a matcher left installed rejects a later test's unrelated file the + // moment that file is handed the inode this row captured. + const previousStat = vi.mocked(fs.stat).getMockImplementation() vi.mocked(fs.stat).mockImplementation(async (backupPath) => { - if (backupPath === unreadableBackup) { + if (await isInjectedInode(backupPath)) { throw Object.assign(new Error("Backup stat failed"), { code }) } return actual.stat(backupPath) }) const merge = vi.fn((existing: unknown) => existing) - if (code === "ENOENT") { - await safeWriteJson(currentTestFilePath, {}, { merge }) - expect(merge).toHaveBeenCalledWith({ committed: true }, {}) - } else { - await expect(safeWriteJson(currentTestFilePath, {}, { merge })).rejects.toMatchObject({ code }) - expect(merge).not.toHaveBeenCalled() - expect(await readFileContent(unreadableBackup)).toEqual({ stale: true }) - expect(await readFileContent(readableBackup)).toEqual({ committed: true }) + try { + if (code === "ENOENT") { + await safeWriteJson(currentTestFilePath, {}, { merge }) + expect(merge).toHaveBeenCalledWith({ committed: true }, {}) + } else { + await expect(safeWriteJson(currentTestFilePath, {}, { merge })).rejects.toMatchObject({ code }) + expect(merge).not.toHaveBeenCalled() + expect(await readFileContent(unreadableBackup)).toEqual({ stale: true }) + expect(await readFileContent(readableBackup)).toEqual({ committed: true }) + } + } finally { + vi.mocked(fs.stat).mockImplementation(previousStat ?? actual.stat) } }, ) @@ -818,4 +841,721 @@ describe("safeWriteJson", () => { const content = await readFileContent(currentTestFilePath) expect(content).toEqual(newData) }) + + // The commit rename targets the symlink referent. The staged temp file must + // therefore be created beside the RESOLVED target — staging beside the link + // would make the commit rename fail with EXDEV when the referent is on + // another filesystem. (Real symlinks are unavailable in this CI lane, so the + // resolution is simulated by mocking fs.realpath the same way.) + test("stages the temp file beside the symlink referent and commits onto it", async () => { + const referentDir = path.join(tempDir, "referent") + const linkDir = path.join(tempDir, "link") + await fs.mkdir(referentDir, { recursive: true }) + await fs.mkdir(linkDir, { recursive: true }) + // caller-visible path (the link) vs the resolved referent path + const callerPath = path.join(linkDir, "test-file.json") + const referentPath = path.join(referentDir, "test-file.json") + // Seed the RESOLVED referent with real content (via the actual fs) so the + // write exercises replacement of an EXISTING referent: the lock, the + // backup, and the commit all target the resolved referent. + await fsPromisesActuals.writeFile!(referentPath, JSON.stringify({ seed: true })) + + // Only the file resolves through the link; the directory is already canonical, + // so the lock key is the referent rather than the alias directory + basename. + vi.spyOn(fs, "realpath").mockImplementation(async (target) => + target === callerPath ? referentPath : String(target), + ) + + await safeWriteJson(callerPath, { after: true }) + + // the temp file was created next to the resolved referent, NOT beside the link + const tempPaths = vi.mocked(fsSyncActual.createWriteStream).mock.calls.map((call) => String(call[0])) + expect(tempPaths.some((p) => p.startsWith(referentDir + path.sep) && p.includes(".new_"))).toBe(true) + expect(tempPaths.some((p) => p.startsWith(linkDir + path.sep))).toBe(false) + + // the content was committed onto the referent + expect(await readFileContent(referentPath)).toEqual({ after: true }) + }) + + // proper-lockfile with realpath:false keys the lock by the given path, so a + // symlink alias and its referent must coordinate through ONE lock on the + // resolved referent — otherwise a concurrent merge through both aliases + // reads the same JSON and overwrites one update. (Real symlinks are + // unavailable in this CI lane, so the resolution is simulated by mocking + // fs.realpath, the same way as the staging test above.) + test("acquires the lock on the resolved referent, not the caller alias", async () => { + vi.resetModules() // fresh module instances so the doMock below is picked up + + const referentDir = path.join(tempDir, "lock-referent") + const linkDir = path.join(tempDir, "lock-link") + await fs.mkdir(referentDir, { recursive: true }) + await fs.mkdir(linkDir, { recursive: true }) + // caller-visible path (the link) vs the resolved referent path + const callerPath = path.join(linkDir, "locked.json") + const referentPath = path.join(referentDir, "locked.json") + await fsPromisesActuals.writeFile!(referentPath, JSON.stringify({ seed: 1 })) + + // Only the file resolves through the link; the directory is already canonical, + // so the lock key is the referent rather than the alias directory + basename. + const realpathSpy = vi + .spyOn(fs, "realpath") + .mockImplementation(async (target) => (target === callerPath ? referentPath : String(target))) + + // Wrap the real lock in a capturing mock, and drive the two rare error paths + // (the onCompromised callback and a failing release) so they stay covered + // without real lockfile staleness. The callback rethrows by design, so + // the mock swallows that throw and lets the real lock proceed. + const realLockfile = await vi.importActual("proper-lockfile") + const lockMockFn = vi.fn( + async ( + file: Parameters[0], + options?: Parameters[1], + ) => { + try { + options?.onCompromised?.(new Error("lock compromised (test)")) + } catch { + // onCompromised rethrows by design; swallow so the real lock proceeds. + } + const release = await realLockfile.lock(file, options) + return async () => { + await release() + throw new Error("release failed (test)") + } + }, + ) + const lockMock: typeof realLockfile.lock = lockMockFn + vi.doMock("proper-lockfile", () => ({ + ...realLockfile, + lock: lockMock, + })) + + // Re-import safeWriteJson so it picks up the mocked proper-lockfile. + const { safeWriteJson: mockedSafeWriteJson } = await import("../safeWriteJson") + + const mergeFn = vi.fn((existing: unknown, incoming: unknown) => ({ + ...(existing as Record), + ...(incoming as Record), + })) + + // Capture the compromise + release-failure logs. + const consoleErrorSpy = vi.spyOn(console, "error") + try { + await mockedSafeWriteJson(callerPath, { added: true }, { merge: mergeFn }) + + // The lock was keyed by the resolved referent — every alias shares it. + expect(lockMock).toHaveBeenCalledTimes(1) + expect(String(lockMockFn.mock.calls[0][0])).toBe(referentPath) + // The merge read the referent's content through that single lock. + expect(mergeFn).toHaveBeenCalledWith({ seed: 1 }, { added: true }) + expect(await readFileContent(referentPath)).toEqual({ seed: 1, added: true }) + // The compromise callback and the failed release were logged, not thrown. + expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining("was compromised"), expect.any(Error)) + expect(consoleErrorSpy).toHaveBeenCalledWith( + expect.stringContaining("Failed to release lock"), + expect.any(Error), + ) + } finally { + // Cleanup must run even when an assertion fails: a leaked mock registration + // or console spy changes later tests. vi.doUnmock is the non-hoisted counterpart + // of the vi.doMock above; vi.unmock is hoisted to the top of the file, so it would + // not undo this registration from here. + realpathSpy.mockRestore() + vi.doUnmock("proper-lockfile") + vi.resetModules() + consoleErrorSpy.mockRestore() + } + }) + + test("rejects a confined write whose target is outside the confined directory", async () => { + const scope = path.join(tempDir, "project") + await fs.mkdir(scope) + const outside = path.join(tempDir, "elsewhere.json") + + // No symlink needed: the check runs on the resolved publish target, so an + // out-of-scope path is rejected on every platform, and it is rejected before the + // lock is taken and before anything is staged. + await expect(safeWriteJson(outside, { mcpServers: {} }, { confineTo: scope })).rejects.toThrow( + ConfinedPathEscapeError, + ) + + const left = await fs.readdir(tempDir) + expect(left).not.toContain("elsewhere.json") + expect(left.filter((entry) => entry.includes(".new_") || entry.endsWith(".lock"))).toEqual([]) + }) + + test.skipIf(process.platform === "win32")( + "rejects a confined write whose symlink resolves outside the confined directory", + async () => { + const projectDir = path.join(tempDir, "project") + await fs.mkdir(projectDir) + const outside = path.join(tempDir, "outside.json") + await fsSyncActual.promises.writeFile(outside, JSON.stringify({ secret: "original" }), "utf8") + // A repository that plants its project settings file as a link to somewhere else + // must not receive the settings write at the linked path. The caller picked + // projectDir/mcp.json from the workspace, so it declares that scope. + const projectConfig = path.join(projectDir, "mcp.json") + await fs.symlink(outside, projectConfig) + + await expect(safeWriteJson(projectConfig, { mcpServers: {} }, { confineTo: projectDir })).rejects.toThrow( + ConfinedPathEscapeError, + ) + + // The linked file is untouched and nothing was staged beside it. + expect(JSON.parse(await fsSyncActual.promises.readFile(outside, "utf8"))).toEqual({ secret: "original" }) + const entries = await fs.readdir(tempDir) + expect(entries).toContain("outside.json") + expect( + entries.filter( + (entry) => entry.includes(".new_") || entry.includes("safeWriteText") || entry.endsWith(".lock"), + ), + ).toEqual([]) + }, + ) + + test.skipIf(process.platform === "win32")( + "confines a write whose symlink referent stays inside the confined directory", + async () => { + const projectDir = path.join(tempDir, "project-in") + await fs.mkdir(projectDir) + const referent = path.join(projectDir, "real-mcp.json") + await fsSyncActual.promises.writeFile(referent, JSON.stringify({ mcpServers: {} }), "utf8") + const alias = path.join(projectDir, "mcp.json") + await fs.symlink(referent, alias) + + // Confining is about the scope, not about forbidding links: a link that stays + // inside the project still publishes to its referent. + await safeWriteJson( + alias, + { mcpServers: { local: { url: "http://localhost" } } }, + { confineTo: projectDir }, + ) + + expect(JSON.parse(await fsSyncActual.promises.readFile(referent, "utf8"))).toEqual({ + mcpServers: { local: { url: "http://localhost" } }, + }) + }, + ) + + test.skipIf(process.platform === "win32")( + "confines a scope path that itself runs through a symlink and does not exist yet", + async () => { + const real = path.join(tempDir, "real-project") + await fs.mkdir(real) + const alias = path.join(tempDir, "alias-project") + await fs.symlink(real, alias) + // The scope is declared through the alias, and the directory it names does not + // exist yet. Resolving it lexically would compare an unresolved scope against a + // fully resolved target and reject a write that is in fact inside the project - + // the macOS /var -> /private/var shape. The nearest existing ancestor is resolved + // and the remainder re-joined instead. + const nested = path.join(alias, "nested") + const target = path.join(nested, "mcp.json") + + await safeWriteJson(target, { mcpServers: {} }, { confineTo: nested }) + + expect( + JSON.parse(await fsSyncActual.promises.readFile(path.join(real, "nested", "mcp.json"), "utf8")), + ).toEqual({ mcpServers: {} }) + }, + ) + + test.skipIf(process.platform === "win32")( + "preserves a restrictive 0o600 target mode through the atomic publish", + async () => { + await fsPromisesActuals.writeFile!(currentTestFilePath, JSON.stringify({ before: true })) + fsSyncActual.chmodSync(currentTestFilePath, 0o600) + + await safeWriteJson(currentTestFilePath, { after: true }) + + expect(fsSyncActual.statSync(currentTestFilePath).mode & 0o777).toBe(0o600) + expect(await readFileContent(currentTestFilePath)).toEqual({ after: true }) + }, + ) + // The two failure paths of _copyTargetMode: a target whose mode cannot be read, and a staged + // file whose mode cannot be set. Both have to log and let the write finish, because the + // replacement protocol - not the mode - is what makes the publish atomic. They are driven + // through the fs/promises mocks rather than a real EACCES/EPERM, because forcing either one + // for real needs privileges a developer box and a CI runner neither have. That is also why + // these two run on every platform while the symlink and mode rows above skip windows. + test("logs and still publishes when the target's mode cannot be read", async () => { + await fsPromisesActuals.writeFile!(currentTestFilePath, JSON.stringify({ before: true })) + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + // fs.stat is already vi.fn() in the factory above - vi.mocked keeps the real + // implementation reachable once this single call is done. + await vi.mocked(fs.stat).mockImplementationOnce(async () => { + const error: NodeJS.ErrnoException = new Error(`EACCES: permission denied, stat '${currentTestFilePath}'`) + error.code = "EACCES" + throw error + }) + + await safeWriteJson(currentTestFilePath, { after: true }) + + expect(await readFileContent(currentTestFilePath)).toEqual({ after: true }) + // The log must name the target it could not read; it must not be compared against + // the caller's spelling. The writer resolves the target before logging, and on + // Windows a path whose components carry 8.3 aliases resolves to a different + // spelling than the one the caller handed it - measured on this row: a temp under + // C:\work\ZOO-CO~1\TMP-AL~2 logged its target as ...\Zoo-Code-fork\.tmp-alias-vps2f\ + // on the same run. The mkdtemp directory name and the file's own name are the parts + // that survive resolution, so the log is pinned to those. + const loggedTargets = consoleErrorSpy.mock.calls.map((call: unknown[]) => String(call[0])).join("\n") + expect(loggedTargets).toContain(path.basename(path.dirname(currentTestFilePath))) + expect(loggedTargets).toContain(path.basename(currentTestFilePath)) + expect(consoleErrorSpy).toHaveBeenCalledWith( + expect.stringContaining(path.basename(currentTestFilePath)), + expect.anything(), + ) + consoleErrorSpy.mockRestore() + }, 20_000) + + test("logs and still publishes when the staged file's mode cannot be set", async () => { + await fsPromisesActuals.writeFile!(currentTestFilePath, JSON.stringify({ before: true })) + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + // chmod is a vi.fn() in the factory above for the same reason. + await vi.mocked(fs.chmod).mockImplementationOnce(async () => { + const error: NodeJS.ErrnoException = new Error( + `EPERM: operation not permitted, chmod '${currentTestFilePath}'`, + ) + error.code = "EPERM" + throw error + }) + + await safeWriteJson(currentTestFilePath, { after: true }) + + expect(await readFileContent(currentTestFilePath)).toEqual({ after: true }) + expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining("Failed to copy mode"), expect.anything()) + consoleErrorSpy.mockRestore() + }, 20_000) + + // Ordering matters for the security guarantee: proper-lockfile creates + // ${lockKey}.lock beside the lock key, and the key is the symlink referent. If + // confinement were checked only after the lock, an out-of-scope target would first + // create a lock directory outside the scope. A lock mock that throws if reached + // proves the check runs first. Written without symlinks so it runs on every lane. + test("rejects an out-of-scope target before the advisory lock is taken", async () => { + vi.resetModules() + const projectDir = path.join(tempDir, "order-project-plain") + await fs.mkdir(projectDir) + const outside = path.join(tempDir, "order-outside-plain.json") + + const realLockfile = await vi.importActual("proper-lockfile") + const lockMockFn = vi.fn(async () => { + throw new Error("lock taken for an out-of-scope target (test)") + }) + vi.doMock("proper-lockfile", () => ({ ...realLockfile, lock: lockMockFn })) + const { safeWriteJson: lockedSafeWriteJson } = await import("../safeWriteJson") + + try { + await expect(lockedSafeWriteJson(outside, { mcpServers: {} }, { confineTo: projectDir })).rejects.toThrow( + /resolves outside the confined directory/, + ) + expect(lockMockFn).not.toHaveBeenCalled() + const entries = await fs.readdir(tempDir) + expect(entries.filter((entry) => entry.endsWith(".lock") || entry.includes(".new_"))).toEqual([]) + } finally { + vi.doUnmock("proper-lockfile") + vi.resetModules() + } + }) + + test("does not create the parent directory of an out-of-scope confined target", async () => { + const projectDir = path.join(tempDir, "scope-dir-project") + await fs.mkdir(projectDir) + // The parent does not exist yet: the mkdir in safeWriteJson would create it - + // a filesystem change outside confineTo - before the confinement check rejected + // the write. + const outside = path.join(tempDir, "scope-missing-parent", "nested.json") + + await expect(safeWriteJson(outside, { mcpServers: {} }, { confineTo: projectDir })).rejects.toThrow( + /resolves outside the confined directory/, + ) + + const entries = await fs.readdir(tempDir) + expect(entries).not.toContain("scope-missing-parent") + expect(entries.filter((entry) => entry.endsWith(".lock") || entry.includes(".new_"))).toEqual([]) + }) + + // A caller that declares a scope must never get the unconstrained path: an + // empty confineTo is a declared scope, not an absent one. This value occurs in + // practice - McpHub.confineForMcpWrite returns getWorkspacePath(), which is "" + // while no workspace folder is open. The truthiness checks skipped both + // confinement gates for "", so the write followed any symlink with no scope + // check at all. + test("rejects a declared-but-empty confineTo instead of writing unconstrained", async () => { + const error = await safeWriteJson(currentTestFilePath, { mcpServers: {} }, { confineTo: "" }).then( + () => undefined, + (reason: unknown) => reason, + ) + expect(error).toBeInstanceOf(ConfinedPathEscapeError) + if (error instanceof ConfinedPathEscapeError) { + // The rejection must name the declared empty root: a substituted root + // (path.resolve("") is the process cwd) would mean confining the write + // to a directory nobody declared. + expect(error.confineTo).toBe("") + } + // The write did not proceed: the target keeps its pre-existing content. + expect(await readFileContent(currentTestFilePath)).toEqual({ initial: "content" }) + }) + + test("rejects an empty confineTo before creating the target parent directory", async () => { + // The same fail-closed decision pinned at the ordering the pre-lock check + // guarantees: a rejected confined write must not create the missing parent + // directory of the target. + const outside = path.join(tempDir, "empty-scope-missing-parent", "nested.json") + + const error = await safeWriteJson(outside, { mcpServers: {} }, { confineTo: "" }).then( + () => undefined, + (reason: unknown) => reason, + ) + expect(error).toBeInstanceOf(ConfinedPathEscapeError) + if (error instanceof ConfinedPathEscapeError) { + expect(error.confineTo).toBe("") + } + + const entries = await fs.readdir(tempDir) + expect(entries).not.toContain("empty-scope-missing-parent") + expect(entries.filter((entry) => entry.endsWith(".lock") || entry.includes(".new_"))).toEqual([]) + }) + + test("rejects a whitespace-only confineTo and names the declared root", async () => { + // path.resolve(" ") is a directory named " " under the process cwd - a + // scope nobody declared. Whitespace-only fails closed with the declared + // root, the same decision as the empty string. + const error = await safeWriteJson(currentTestFilePath, { mcpServers: {} }, { confineTo: " " }).then( + () => undefined, + (reason: unknown) => reason, + ) + expect(error).toBeInstanceOf(ConfinedPathEscapeError) + if (error instanceof ConfinedPathEscapeError) { + expect(error.confineTo).toBe(" ") + } + expect(await readFileContent(currentTestFilePath)).toEqual({ initial: "content" }) + }) + + // The confinement option decides from the resolved publish target and stops at its final + // component. An ancestor DIRECTORY replaced by a link is caught fail-closed by a re-check + // taken immediately before the commit rename, and a swap that lands inside the sliver between + // that check and the rename is caught by the re-check after the commit, which undoes an + // escaped write. These tests are that contract as an executable set - one for the + // swapped ancestor, one for the directory that already holds a file at the target name, + // one for the undo itself. The swap is driven from the merge + // callback, which safeWriteJson invokes after the in-lock confinement check and before + // anything is staged, so the ancestor moves inside the window rather than hopefully so. + // A directory link needs no privilege on win32 as a junction; "dir" is the POSIX + // spelling. Both make the ancestor itself the link, which is the shape under test. + const ancestorLinkKind = process.platform === "win32" ? ("junction" as const) : ("dir" as const) + + function swapAncestorAfterTheCheck(ancestor: string, pointsAt: string): void { + fsSyncActual.renameSync(ancestor, ancestor + "-moved-aside") + fsSyncActual.symlinkSync(pointsAt, ancestor, ancestorLinkKind) + } + + test("refuses and undoes the publish when an ancestor is swapped after the final check", async () => { + const projectDir = path.join(tempDir, "swap-project") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + const target = path.join(ancestor, "mcp.json") + await fs.writeFile(target, JSON.stringify({ inside: true })) + // The swapped-in directory has no file at the target name yet, so the shape under test is + // the swapped ancestor itself: the re-check before the commit rename sees the escape and + // the write never publishes. + const swappedIn = path.join(tempDir, "elsewhere", "settings") + await fs.mkdir(swappedIn, { recursive: true }) + + // The confinement option fails closed on the swapped ancestor: the re-check taken + // before the commit rename re-resolves the publish target, sees it outside the + // declared scope, and reports the escape before any rename can land. + await expect( + safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + merge: () => { + swapAncestorAfterTheCheck(ancestor, swappedIn) + return { written: "payload" } + }, + }, + ), + ).rejects.toBeInstanceOf(ConfinedPathEscapeError) + + // Nothing was published outside the scope: the commit never ran, so the directory + // that was swapped in is still empty... + expect(fsSyncActual.existsSync(path.join(swappedIn, "mcp.json"))).toBe(false) + // ...and the file that was inside the scope keeps its pre-write bytes - the + // publish did not reach it under the moved-aside name either. + expect(JSON.parse(fsSyncActual.readFileSync(path.join(ancestor + "-moved-aside", "mcp.json"), "utf8"))).toEqual( + { inside: true }, + ) + // The scope was declared and active in this very fixture: with the ancestor left + // alone, the same option refuses an out-of-scope target. Without this contrast the + // escape above would also be the outcome of a confinement check that never ran. + await expect( + safeWriteJson(path.join(tempDir, "elsewhere", "other.json"), { other: true }, { confineTo: projectDir }), + ).rejects.toThrow(ConfinedPathEscapeError) + }) + + test("keeps the file that already sits in the swapped-in directory when the commit path escapes", async () => { + const projectDir = path.join(tempDir, "swap-project-held") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + const target = path.join(ancestor, "mcp.json") + await fs.writeFile(target, JSON.stringify({ inside: true })) + // The other half of the window: the swapped-in directory already holds a file at the + // target name, so a commit rename would replace bytes this write never read before + // any re-check could see the escape. + const swappedIn = path.join(tempDir, "elsewhere-held", "settings") + await fs.mkdir(swappedIn, { recursive: true }) + const heldFile = path.join(swappedIn, "mcp.json") + fsSyncActual.writeFileSync(heldFile, JSON.stringify({ outside: "peer bytes" })) + + await expect( + safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + merge: () => { + swapAncestorAfterTheCheck(ancestor, swappedIn) + return { written: "payload" } + }, + }, + ), + ).rejects.toBeInstanceOf(ConfinedPathEscapeError) + + // The commit never ran, so the file that already sat at the escaped name keeps its + // own bytes: the ask is that the rename not replace them. + expect(JSON.parse(fsSyncActual.readFileSync(heldFile, "utf8"))).toEqual({ outside: "peer bytes" }) + // The file inside the scope keeps its pre-write bytes under the moved-aside name. + expect(JSON.parse(fsSyncActual.readFileSync(path.join(ancestor + "-moved-aside", "mcp.json"), "utf8"))).toEqual( + { inside: true }, + ) + // Nothing this write staged is left in the directory that was moved aside. + expect(fsSyncActual.readdirSync(ancestor + "-moved-aside").filter((name) => name.includes(".new_"))).toEqual([]) + // What it does leave in the directory that was swapped in is its own staged file: the + // escape branch of the teardown rethrows before the staged cleanup that sits below it, + // so refusing the commit leaves the staging name behind. That leftover is the gap the + // sibling thread on this pull carries, and this row pins it rather than hiding it. + const leftovers = fsSyncActual.readdirSync(swappedIn).filter((name) => name !== "mcp.json") + expect(leftovers).toHaveLength(1) + expect(String(leftovers[0])).toMatch(/^\.mcp\.json\.new_\d+_[a-z0-9]+\.tmp$/) + }) + + test("undoes an escaped publish only when the bytes on disk are still this write's bytes", async () => { + const outside = path.join(tempDir, "undo-escaped") + await fs.mkdir(outside, { recursive: true }) + const escaped = path.join(outside, "mcp.json") + // A peer wrote its own file at the escaped name after our commit published ours and + // before the post-commit re-check ran. Removing it on the name alone would delete the + // peer's file; the byte comparison must leave it in place. + fsSyncActual.writeFileSync(escaped, JSON.stringify({ peer: true })) + + await undoEscapedPublish(escaped, Buffer.from(JSON.stringify({ ours: true }))) + + expect(fsSyncActual.existsSync(escaped)).toBe(true) + expect(JSON.parse(fsSyncActual.readFileSync(escaped, "utf8"))).toEqual({ peer: true }) + + // The bytes are still ours: the escaped publish is undone. + await undoEscapedPublish(escaped, Buffer.from(JSON.stringify({ peer: true }))) + expect(fsSyncActual.existsSync(escaped)).toBe(false) + + // A missing file and an unreadable byte record are both no-ops, never a throw. + await undoEscapedPublish(escaped, Buffer.from("{}")) + await undoEscapedPublish(path.join(outside, "absent.json"), undefined) + }) + + // The confinement re-check inside the failure path at lines 492 to 517 of safeWriteJson.ts runs + // while the write is already failing, and the review says a rejection there must not decide + // what the teardown does: the backup rollback at lines 522 to 538 and the staged cleanup at + // lines 540 to 556 are what keep the committed copy and the staged bytes from being left + // behind. This row drives the same EPERM fallback the row at line 192 drives, so a backup + // exists and the canonical path is absent when the catch block runs, and it breaks fs.realpath + // only from the moment that backup rename lands, which is the state the catch block then reads. + test("restores the committed file and drops the staged file when the failure-path confinement check cannot run", async () => { + const initialData = { message: "Initial content, must survive a broken teardown check" } + const newData = { message: "New content" } + await fsPromisesActuals.writeFile!(currentTestFilePath, JSON.stringify(initialData)) + + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + let teardownCheckBroken = false + const realpathSpy = vi.spyOn(fs, "realpath").mockImplementation(async (target) => { + if (teardownCheckBroken) { + throw Object.assign(new Error("EPERM: operation not permitted, realpath"), { code: "EPERM" }) + } + return String(target) + }) + let renameCallCount = 0 + vi.mocked(fs.rename).mockImplementation(async (oldPath, newPath) => { + renameCallCount++ + if (renameCallCount === 1) { + // The single-rename commit fails with EPERM, which starts the two-step fallback. + throw Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" }) + } + if (renameCallCount === 2) { + // The backup lands here. From this point the failing write is what the catch block + // sees, and the confinement re-check inside it is the thing under test. + teardownCheckBroken = true + return fsPromisesActuals.rename!(oldPath, newPath) + } + if (renameCallCount === 3) { + throw new Error("Fallback replacement rename failed") + } + // The rollback rename, which is what this row is about. + return fsPromisesActuals.rename!(oldPath, newPath) + }) + + try { + // The write rejects with the failure that started the teardown, not with the realpath + // rejection of a scope root that could not be canonicalized. + await expect(safeWriteJson(currentTestFilePath, newData, { confineTo: tempDir })).rejects.toThrow( + "Fallback replacement rename failed", + ) + // The rollback ran: the committed copy is back at the canonical path. + expect(await fileExists(currentTestFilePath)).toBe(true) + expect(await readFileContent(currentTestFilePath)).toEqual(initialData) + // Neither a backup nor a staged file outlives the failed write. + const leftovers = (await fs.readdir(tempDir)).filter( + (entry) => entry.includes(".bak_") || entry.includes(".new_"), + ) + expect(leftovers).toEqual([]) + // A re-check that could not run is reported rather than silently skipped. + expect(consoleErrorSpy).toHaveBeenCalledWith( + expect.stringContaining("could not run during the teardown"), + expect.objectContaining({ code: "EPERM" }), + ) + } finally { + realpathSpy.mockRestore() + consoleErrorSpy.mockRestore() + } + }) + + // The re-check inside the failure path has a second shape, and no row reached it: the publish + // target canonicalizes and only the confined scope fails. The row above breaks fs.realpath for + // every path once its flag lands, so line 503 throws too, publishedPath never gets a value, and + // the log-and-continue at lines 516 to 519 runs with BOTH resolutions unresolved - which is not + // the state line 507 is written to distinguish. This row keeps the target resolvable and fails + // fs.realpath on the confined scope alone, so line 503 lands, line 504 throws, and the + // log-and-continue runs with publishedPath set and scopeRoot undefined. The array below is this + // row's own witness, recorded inside its mock, of which resolutions were attempted while the + // write was already failing and in what order. + test("reports the scope root failure and still rolls back when only the confined scope cannot be canonicalized", async () => { + const initialData = { message: "Initial content, must survive a scope root that cannot resolve" } + const newData = { message: "New content" } + await fsPromisesActuals.writeFile!(currentTestFilePath, JSON.stringify(initialData)) + + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + let teardownCheckBroken = false + const resolutionsWhileFailing: string[] = [] + // Distinctly worded so the diagnostic this row asserts can only be met by this failure. + const scopeRootFailure = Object.assign( + new Error("EPERM: operation not permitted, realpath of the confined scope"), + { code: "EPERM" }, + ) + const realpathSpy = vi.spyOn(fs, "realpath").mockImplementation(async (target) => { + if (teardownCheckBroken) { + resolutionsWhileFailing.push(String(target)) + // Only the confined scope fails here. The publish target still canonicalizes. + if (path.resolve(String(target)) === tempDir) { + throw scopeRootFailure + } + } + return String(target) + }) + let renameCallCount = 0 + vi.mocked(fs.rename).mockImplementation(async (oldPath, newPath) => { + renameCallCount++ + if (renameCallCount === 1) { + // The single-rename commit fails with EPERM, which starts the two-step fallback. + throw Object.assign(new Error("EPERM: operation not permitted"), { code: "EPERM" }) + } + if (renameCallCount === 2) { + // The backup lands here, so the failing write is what the catch block then reads. + teardownCheckBroken = true + return fsPromisesActuals.rename!(oldPath, newPath) + } + if (renameCallCount === 3) { + throw new Error("Fallback replacement rename failed") + } + // The rollback rename. + return fsPromisesActuals.rename!(oldPath, newPath) + }) + + try { + // The caller still sees the failure that started the teardown, not the realpath rejection + // of a scope that could not be canonicalized. + await expect(safeWriteJson(currentTestFilePath, newData, { confineTo: tempDir })).rejects.toThrow( + "Fallback replacement rename failed", + ) + // Line 503 landed and line 504 threw, in that order, and nothing else was canonicalized + // while the write was failing: publishedPath is set and scopeRoot is undefined. + expect(resolutionsWhileFailing).toEqual([currentTestFilePath, tempDir]) + // The re-check that could not run is reported rather than silently skipped, and what it + // reported is the scope resolution it actually met. + expect(consoleErrorSpy).toHaveBeenCalledWith( + expect.stringContaining("could not run during the teardown"), + expect.objectContaining({ + message: "EPERM: operation not permitted, realpath of the confined scope", + code: "EPERM", + }), + ) + // The log-and-continue does not decide the teardown: the rollback ran, so the committed copy + // is back at the canonical path with its own bytes. + expect(await fileExists(currentTestFilePath)).toBe(true) + expect(await readFileContent(currentTestFilePath)).toEqual(initialData) + // And neither a backup nor a staged file outlives the failed write. + const leftovers = (await fs.readdir(tempDir)).filter( + (entry) => entry.includes(".bak_") || entry.includes(".new_"), + ) + expect(leftovers).toEqual([]) + } finally { + realpathSpy.mockRestore() + consoleErrorSpy.mockRestore() + } + }) + + // Line 343 is the recovery call, and this pull changed its argument from the caller's + // spelling to the resolved publish target. The two spellings only differ when the + // orphaned replacement files sit beside the referent rather than beside the alias, which + // is the crash state below. Real symlinks are unavailable in this lane, so the link is + // simulated by mocking fs.realpath the same way the staging and lock-key rows do. + test("recovers an orphaned backup found beside the resolved target, not the caller alias", async () => { + const referentDir = path.join(tempDir, "recover-referent") + const aliasDir = path.join(tempDir, "recover-alias") + await fs.mkdir(referentDir, { recursive: true }) + await fs.mkdir(aliasDir, { recursive: true }) + const callerPath = path.join(aliasDir, "history.json") + const referentPath = path.join(referentDir, "history.json") + // Crash state of the two-step replacement seen through the link: the committed bytes + // live in an orphaned backup next to the referent, the referent itself is absent, and + // the alias directory holds no replacement files at all. + const backupPath = path.join(referentDir, ".history.json.bak_1_last.tmp") + const committed = { history: ["committed before the interruption"] } + await fs.writeFile(backupPath, JSON.stringify(committed)) + // Only the file resolves through the link; both directories are already canonical, so + // the scan directory is the one place the two spellings disagree. + const realpathSpy = vi + .spyOn(fs, "realpath") + .mockImplementation(async (target) => (target === callerPath ? referentPath : String(target))) + const merge = vi.fn((existing: unknown, incoming: unknown) => ({ + ...(existing as Record), + ...(incoming as Record), + })) + const trace = vi.fn() + try { + await safeWriteJson(callerPath, { added: true }, { merge, trace }) + // Recovery scanned the resolved target, so the merge callback read the committed + // history instead of reporting an absent file. + expect(merge).toHaveBeenCalledExactlyOnceWith(committed, { added: true }) + // The restore is reported through the same trace channel the writer already uses. + expect(trace).toHaveBeenCalledWith({ stage: "recover", detail: backupPath }) + expect(await readFileContent(referentPath)).toEqual({ + history: ["committed before the interruption"], + added: true, + }) + // The restored backup was consumed: the leftover does not outlive the write. + expect(fsSyncActual.existsSync(backupPath)).toBe(false) + } finally { + realpathSpy.mockRestore() + } + }) }) diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts index 49807ea154..0705f771cc 100644 --- a/src/utils/fileLock.ts +++ b/src/utils/fileLock.ts @@ -1,6 +1,7 @@ import * as path from "path" import { tracePersistenceEvent } from "../core/task-persistence/persistenceTrace" import * as lockfile from "proper-lockfile" +import * as fs from "fs/promises" /** * Shared staleness window for per-file advisory locks. This module owns the @@ -19,6 +20,91 @@ export interface FileLockOptions { immediate?: boolean } +/** + * Canonical lock key for a path. + * + * proper-lockfile derives its lock file from the path it is handed, and this module + * turns off the library's own realpath step because the file may not exist yet. Two + * callers that reach the same file by different routes - one lexical, one through a + * symlinked directory - would then take DIFFERENT locks and silently lose updates + * against each other, which is exactly how a task file written through a symlinked + * task directory ends up unlocked against a task-history delete. + * + * The file itself may be absent (a create), so the nearest EXISTING ancestor is + * canonicalized and the missing components are re-appended. If nothing can be + * canonicalized the lexical absolute path is kept: lock keys stay stable and the + * write's own resolution still decides where content lands. + */ +/** + * Total link hops canonicalLockPath may follow across ALL its frames. The + * per-frame walk bound alone does not terminate: a cycle whose length does not + * divide that bound (a 3-link cycle a -> b -> c -> a against a bound of 8) + * makes every frame land on a different cycle member, so the recursion below + * restarts its budget forever. This runs on the lock path - withFileLock and every + * direct acquireFileLock caller hands it a cycle member - so an unbounded walk hangs + * guardedWrite and safeWriteJson, not just the walker. + */ +const MAX_TOTAL_LINK_HOPS = 64 + +async function canonicalLockPath(filePath: string, remainingLinkHops = MAX_TOTAL_LINK_HOPS): Promise { + const absoluteFilePath = path.resolve(filePath) + + // A file symlink has to produce the same key the writer's lock uses + // (resolveLockKey in safeWriteText). Walking readlink even when the referent is + // temporarily absent - which is exactly the window a backup-mode commit creates - + // keeps a raw withFileLock caller on the link path excluding the peer writing + // through the referent; re-appending the link's basename onto the canonical + // parent would take a different lock and the two operations would stop excluding + // each other. The walk is bounded so a two-link cycle terminates. + let linkCursor = absoluteFilePath + const frameBudget = Math.min(8, remainingLinkHops) + for (let depth = 0; depth < frameBudget; depth++) { + const referent = await fs.readlink(linkCursor).catch(() => undefined) + if (referent === undefined) { + break + } + // A relative referent is relative to the link's REAL parent, not to the spelling the + // caller arrived with. Under a symlinked directory `..` names the referent's parent, so + // joining lexically produces a key for a different file and the writer through the alias + // stops excluding the writer through the referent. When the parent itself cannot be + // canonicalized (a dangling chain) the lexical join is the only answer available. + const parentReal = path.isAbsolute(referent) + ? undefined + : await fs.realpath(path.dirname(linkCursor)).catch(() => undefined) + linkCursor = path.resolve(parentReal ?? path.dirname(linkCursor), referent) + } + if (linkCursor !== absoluteFilePath) { + // Recurse with the REMAINING hop budget, not a fresh one: once the total + // is spent the next frame walks zero hops and canonicalizes the ancestors + // of the cycle member it stopped on, so a cycle terminates on a stable key + // instead of recursing forever. + return await canonicalLockPath(linkCursor, Math.max(0, remainingLinkHops - frameBudget)) + } + const missing: string[] = [] + let cursor = absoluteFilePath + for (;;) { + try { + const realPath = await fs.realpath(cursor) + return missing.length > 0 ? path.join(realPath, ...missing.reverse()) : realPath + } catch (error) { + const code = + typeof error === "object" && error !== null && "code" in error + ? (error as { code?: string }).code + : undefined + // Only a missing component may be walked over. An ancestor that exists but cannot be + // inspected (EACCES on a parent, ELOOP, EIO) means the canonical key is UNKNOWN, and a + // lexical key is a different lock from the one a peer that reached the same file through + // the referent holds: taking it lets both run at once. Fail closed rather than invent a + // key - the fallback below is only for "nothing here yet". + if (code !== "ENOENT" && code !== "ENOTDIR") throw error + const parent = path.dirname(cursor) + if (parent === cursor) return absoluteFilePath + missing.push(path.basename(cursor)) + cursor = parent + } + } +} + /** * Acquire the advisory lock for one file path using the exact protocol * `safeWriteJson` uses, so operations that hold this lock serialize with @@ -26,9 +112,22 @@ export interface FileLockOptions { * returned function exactly once and must not acquire the same lock again * while holding it. */ -export async function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<() => Promise> { - const absoluteFilePath = path.resolve(filePath) - if (options?.waitForStaleLock) tracePersistenceEvent("json-lock-wait", { filePath: absoluteFilePath }) +/** + * The number of times withFileLock will release and retake the lock when the canonical key + * of the path moves underneath it. A flapping link is pathological; the bound exists so a + * walk that keeps answering differently terminates with an error instead of spinning. + */ +const MAX_LOCK_KEY_RETARGETS = 3 + +/** + * Take the advisory lock for a key that is already canonical. + * + * Split out of acquireFileLock so withFileLock can retake the lock for a re-derived key + * without re-running the canonicalization inside the acquire step: that is what lets it prove + * the lock it holds while running the callback is the lock a peer reaching the same file + * through any other spelling would take. + */ +async function _lockCanonicalKey(absoluteFilePath: string, options?: FileLockOptions): Promise<() => Promise> { try { return await lockfile.lock(absoluteFilePath, { stale: LOCK_STALE_MS, @@ -61,6 +160,12 @@ export async function acquireFileLock(filePath: string, options?: FileLockOption } } +export async function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<() => Promise> { + const absoluteFilePath = await canonicalLockPath(filePath) + if (options?.waitForStaleLock) tracePersistenceEvent("json-lock-wait", { filePath: absoluteFilePath }) + return _lockCanonicalKey(absoluteFilePath, options) +} + /** * Run one operation while holding the advisory lock for a file path. * Callers must not acquire this lock again from inside `operation`, and @@ -72,29 +177,65 @@ export async function withFileLock( operation: (absoluteFilePath: string) => Promise, options?: FileLockOptions, ): Promise { - const absoluteFilePath = path.resolve(filePath) - const releaseLock = await acquireFileLock(absoluteFilePath, options) + // The operation receives the caller's own resolved path. On Windows realpath can answer + // with the 8.3 short form (C:\Users\RUNNER~1\... for a temp dir under + // C:\Users\runneradmin\...), and the operation's own file calls (e.g. the task-history + // unlink) must keep the caller's alias semantics: unlinking the referent instead of the + // alias would delete a different directory entry. + const operationPath = path.resolve(filePath) + // The LOCK key is canonical - the same one safeWriteJson computes - so a caller that + // reaches the file through a symlinked directory and one that reaches it lexically + // contend for ONE lock file. Locking the raw path here would let a deletion through this + // helper run concurrently with a safeWriteJson read-modify-write on the referent, breaking + // the compound atomicity the deletion contract promises. The canonicalization runs inside + // acquireFileLock, so the walk happens once and direct acquireFileLock callers (safeWriteJson + // passes an already-canonical key, jsonFileRecovery and the specs pass raw paths) are all + // covered by the same rule. + let lockKey = await canonicalLockPath(operationPath) + if (options?.waitForStaleLock) tracePersistenceEvent("json-lock-wait", { filePath: lockKey }) + + for (let attempt = 0; ; attempt++) { + const releaseLock = await _lockCanonicalKey(lockKey, options) + + // A directory component on this path can be swapped while this call waits for the lock, + // so the key acquired above may no longer be the canonical key of the path the callback + // is about to mutate: the mutation would then run while holding a lock no peer is + // contending for, and a concurrent merge could recreate what the callback deletes. Re-derive + // the key under the same rules before running anything, and on a change release, retake the + // lock for the new key, and only then run the callback. + const currentKey = await canonicalLockPath(operationPath).catch(() => lockKey) + if (currentKey !== lockKey) { + await releaseLock().catch(() => undefined) + if (attempt >= MAX_LOCK_KEY_RETARGETS) { + throw new Error( + `Lock key for ${operationPath} kept moving across ${MAX_LOCK_KEY_RETARGETS} retargets -- the operation was not run.`, + ) + } + lockKey = currentKey + continue + } + + let result: T + try { + result = await operation(operationPath) + } catch (operationError) { + // The operation error is the primary failure. Release without + // reporting a secondary release error over it. + try { + await releaseLock() + } catch (releaseError) { + console.error(`Failed to release lock for ${operationPath}:`, releaseError) + } + throw operationError + } - let result: T - try { - result = await operation(absoluteFilePath) - } catch (operationError) { - // The operation error is the primary failure. Release without - // reporting a secondary release error over it. try { await releaseLock() } catch (releaseError) { - console.error(`Failed to release lock for ${absoluteFilePath}:`, releaseError) + // The operation already succeeded, so a release failure is only + // logged, matching how `safeWriteJson` handles release failures. + console.error(`Failed to release lock for ${operationPath}:`, releaseError) } - throw operationError - } - - try { - await releaseLock() - } catch (releaseError) { - // The operation already succeeded, so a release failure is only - // logged, matching how `safeWriteJson` handles release failures. - console.error(`Failed to release lock for ${absoluteFilePath}:`, releaseError) + return result } - return result } diff --git a/src/utils/safeWriteJson.ts b/src/utils/safeWriteJson.ts index e54b8c51d3..ab05066fff 100644 --- a/src/utils/safeWriteJson.ts +++ b/src/utils/safeWriteJson.ts @@ -3,6 +3,8 @@ import * as fsSync from "fs" import * as path from "path" import { JsonStreamStringify } from "json-stream-stringify" +import { resolveLockKey, resolvePublishTarget } from "../services/file-safety/safeWriteText" + import { getErrorCode } from "./errorCode" import { acquireFileLock } from "./fileLock" import { recoverInterruptedReplacement } from "./jsonFileRecovery" @@ -46,6 +48,52 @@ export interface SafeWriteJsonOptions { * to emit diagnostic trace lines; it never influences the write itself. */ trace?: SafeWriteJsonTrace + /** + * Restrict the write to a directory. The publish target is resolved through + * symlinks before this check runs, so a caller that picked the path from a + * known scope (a workspace, a project settings directory) can refuse a write + * that a planted symlink would land somewhere else. The check runs before the + * advisory lock is taken and before anything is staged, and it is repeated on + * the resolved publish target inside the lock so a peer writer that moved the + * referent in between is caught too. Confinement is active whenever this option + * is DEFINED: a declared root that is empty or whitespace-only is rejected + * rather than silently disabling the checks. + * + * Three checks run: before the advisory lock is taken, on the resolved publish + * target inside the lock, and immediately before the commit rename. Each decides + * the final component as it resolves at its own instant, and publication is path + * based - the parent-directory creation and the commit rename both take a path - + * so an ancestor DIRECTORY swapped for a link after a check redirects whatever + * that check did not refuse. What remains uncovered is the sliver between the + * re-check before the rename and the rename itself: a swap that lands there + * publishes outside the declared scope, and because the rename takes a path it + * replaces whatever file sits where it lands, including a file this write never + * read. The re-check after the commit sees that escape and removes exactly the + * bytes this write published there, but it cannot give back content the rename + * already replaced. This option claims no containment across that sliver. Making + * the claim cover it needs a publish that walks from an already-open directory + * handle with no-follow semantics (openat/renameat over a directory fd); this + * runtime exposes neither, so the claim is narrowed here instead of being made + * true. A caller that needs containment across that sliver cannot get it from + * this option. + */ + confineTo?: string +} + +/** + * Thrown when a write declared with `confineTo` resolves outside that directory. + */ +export class ConfinedPathEscapeError extends Error { + constructor( + readonly requestedPath: string, + readonly resolvedPath: string, + readonly confineTo: string, + ) { + super( + `Refusing to write ${resolvedPath}: it resolves outside the confined directory ${confineTo} (requested ${requestedPath}).`, + ) + this.name = "ConfinedPathEscapeError" + } } function createTempFilePath(absoluteFilePath: string, kind: "new" | "bak"): string { @@ -55,6 +103,111 @@ function createTempFilePath(absoluteFilePath: string, kind: "new" | "bak"): stri ) } +/** + * Canonicalize the directory a write is confined to. The publish target is fully + * resolved through symlinks, so the scope has to be resolved the same way or a + * scope path that itself runs through a symlink (macOS /var -> /private/var is the + * common case) would compare lexically against a resolved target and reject every + * legitimate in-scope write. When the scope does not exist yet, the nearest + * existing ancestor is resolved and the remainder re-appended. + */ +async function _resolveScopeRoot(confineTo: string): Promise { + const lexical = path.resolve(confineTo) + try { + return await fs.realpath(lexical) + } catch (error: unknown) { + // Only a missing path means "walk up and re-join". EACCES or ELOOP means the + // scope cannot be canonicalized at all, and continuing would build a partly + // lexical root that can disagree with the canonical target - the failure has to + // surface rather than decide the scope from a guess. + if (getErrorCode(error) !== "ENOENT") { + throw error + } + const missing: string[] = [] + let ancestor = lexical + while (true) { + const parent = path.dirname(ancestor) + if (parent === ancestor) { + return lexical + } + missing.push(path.basename(ancestor)) + ancestor = parent + try { + const real = await fs.realpath(ancestor) + return path.join(real, ...missing.reverse()) + } catch (innerError: unknown) { + if (getErrorCode(innerError) !== "ENOENT") { + throw innerError + } + } + } + } +} + +/** + * Reject a candidate publish path that escapes the caller's confined scope. + * Shared by the pre-lock check and the in-lock check so both canonicalize the + * same way: the candidate is resolved through symlinks and compared against the + * resolved scope root. + */ +function _assertWithinScope(requestedPath: string, candidatePath: string, scopeRoot: string): void { + const relative = path.relative(scopeRoot, candidatePath) + if (relative === "" || relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) { + throw new ConfinedPathEscapeError(requestedPath, candidatePath, scopeRoot) + } +} + +/** + * The scope root a caller declared, or undefined when no scope was declared. + * Confinement is active whenever confineTo is DEFINED: a declared root that is + * empty or whitespace-only cannot contain any canonicalized path - path.resolve("") + * is the process cwd, not the scope the caller named - so it fails closed here + * instead of silently disabling the checks below, which would let the write + * follow any symlink with no scope check at all. Both confinement checks key off + * this single decision, so they can never disagree about whether a scope is + * active. + */ +function _declaredScopeRoot(confineTo: string | undefined, requestedPath: string): string | undefined { + if (confineTo === undefined) { + return undefined + } + if (confineTo.trim() === "") { + throw new ConfinedPathEscapeError(requestedPath, requestedPath, confineTo) + } + return confineTo +} + +/** + * Undo exactly the file this write published at the escaped location. + * + * The path alone cannot prove the file is ours: a concurrent writer can replace it + * between the commit and this re-check, and unlinking on the name would then delete a + * peer's file. The bytes this write staged are therefore compared with the bytes now on + * disk, and a mismatch leaves the peer's file untouched. The escape is reported to the + * caller either way. + * @internal Exported for the escape-undo regression tests. + */ +export async function undoEscapedPublish(publishedPath: string, expectedBytes: Buffer | undefined): Promise { + if (expectedBytes === undefined) { + return + } + const before = await fs.stat(publishedPath, { bigint: true }).catch(() => undefined) + if (!before) { + return + } + const actualBytes = await fs.readFile(publishedPath).catch(() => undefined) + if (actualBytes === undefined || !actualBytes.equals(expectedBytes)) { + return + } + // Re-stat immediately before the unlink: a peer may have replaced the file between + // the read and the delete, and unlinking it would remove that peer's content. + const after = await fs.stat(publishedPath, { bigint: true }).catch(() => undefined) + if (!after || after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size) { + return + } + await fs.unlink(publishedPath).catch(() => {}) +} + /** * Safely writes JSON data to a file. * - Creates parent directories if they don't exist @@ -62,6 +215,7 @@ function createTempFilePath(absoluteFilePath: string, kind: "new" | "bak"): stri * - Recovers an interrupted previous write before touching the file: restores an orphaned backup when the canonical path is absent, and removes leftover temp files. * - Writes to a temporary file first, then commits it with a single atomic rename, so the committed target stays readable through an interrupted write. * - When a single rename over the target fails with EPERM (a reader holds the file open on Windows), falls back to backing the target up before replacing it. + * - With confineTo declared, refuses a publish whose resolved target lands outside that directory, before the lock and again under it. * - Attempts to roll back and clean up in case of errors. * - Supports pretty-printing with indentation while maintaining streaming efficiency. * @@ -78,6 +232,37 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // For directory creation const dirPath = path.dirname(absoluteFilePath) + // Ensure directory structure exists with improved reliability + // Declared outside the protected block so the catch and finally can still name + // the target when the resolution itself rejects. + let resolvedTargetPath: string | undefined + + // Confinement is decided once, up front, so both checks below agree on whether a + // scope is active: active whenever confineTo is defined, with a declared-but-empty + // root failing closed before the lock key is resolved, before the lock is taken, + // before any directory is created, and before anything is staged. + const confinementRoot = _declaredScopeRoot(options?.confineTo, absoluteFilePath) + + // Lock key: the symlink referent when the path is an existing symlink, so a + // symlink alias and its referent share one lock. The key must be computable + // while a peer writer is mid-commit (backup mode renames the referent away and + // back), so the walk tolerates a dangling link instead of rejecting it here. + let lockKey = await resolveLockKey(absoluteFilePath) + + // Confinement, if the caller declared a scope, is checked BEFORE the lock is + // Also before the parent-directory creation below: an out-of-scope target with a + // missing parent would otherwise get a directory created outside confineTo. + // taken: proper-lockfile creates ${lockKey}.lock beside the lock key, and the key + // is the symlink referent, so a repository-planted link out of the scope would + // otherwise create a lock directory outside the scope (and an unwritable referent + // directory would surface a lock-acquisition error after retries instead of + // ConfinedPathEscapeError). Repeated on the resolved publish target inside the + // lock, since a peer writer may move the referent in between. + if (confinementRoot !== undefined) { + const scopeRoot = await _resolveScopeRoot(confinementRoot) + _assertWithinScope(absoluteFilePath, await _resolveScopeRoot(lockKey), scopeRoot) + } + // Ensure directory structure exists with improved reliability try { // Create directory with recursive option @@ -97,17 +282,67 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // remains a no-op, so the finally block in the main file operations // try-catch-finally won't try to release an unacquired lock if this // path is taken. - releaseLock = await acquireFileLock(absoluteFilePath) + releaseLock = await acquireFileLock(lockKey) + + // Declared before the protected block so the catch can name the bytes an escaped + // publish left behind; the assignment below stays where our copy put it. + let stagedBytes: Buffer | undefined // Variables to hold the actual paths of temp files if they are created. let actualTempNewFilePath: string | null = null let actualTempBackupFilePath: string | null = null try { + // Resolve the publish target under the lock: the peer has committed by now, so + // the strict dangling-link rejection still applies to a real dangling link. It + // must stay inside the protected block, otherwise a rejection here leaves the + // advisory lock held until the stale timeout for every other writer. + resolvedTargetPath = await resolvePublishTarget(absoluteFilePath) + + // The key was computed before the lock was taken, but the publish target is resolved + // under it: a symlink retargeted in between means this writer holds the OLD referent's + // lock and would merge into the new one. Re-derive the key and move to it before + // staging, so every writer through the current referent queues behind the same lock. + for (let attempt = 0; attempt < 3; attempt++) { + const recomputedLockKey = await resolveLockKey(absoluteFilePath) + if (recomputedLockKey === lockKey) { + break + } + if (confinementRoot !== undefined) { + const scopeRoot = await _resolveScopeRoot(confinementRoot) + _assertWithinScope(absoluteFilePath, await _resolveScopeRoot(recomputedLockKey), scopeRoot) + } + await releaseLock() + releaseLock = async () => {} + lockKey = recomputedLockKey + releaseLock = await acquireFileLock(lockKey) + resolvedTargetPath = await resolvePublishTarget(absoluteFilePath) + } + if ((await resolveLockKey(absoluteFilePath)) !== lockKey) { + throw new Error( + `safeWriteJson: refusing to publish ${absoluteFilePath}: the resolved target kept changing while acquiring the lock`, + ) + } + + // Confinement, if the caller declared a scope. Both sides are canonicalized the + // same way: the publish target is resolved through symlinks, and a target that + // does not exist yet still carries the alias components of the path it was + // given. This runs before the merge read and before anything is staged, so a + // rejected write leaves nothing behind. It decides the final component as it + // resolves here, so an ancestor directory replaced by a link after this point is + // outside its reach. The re-check below the staging flush, taken immediately + // before the commit rename, is what narrows that window, and the re-check after + // the commit is the backstop for a swap that lands inside what is left of it. + // See the confineTo option doc for what each of the three checks claims. + if (confinementRoot !== undefined) { + const scopeRoot = await _resolveScopeRoot(confinementRoot) + _assertWithinScope(absoluteFilePath, await _resolveScopeRoot(resolvedTargetPath), scopeRoot) + } + // Heal any state an interrupted previous write left behind: an absent // canonical path with an orphaned backup, or leftover replacement // files. Runs first so a merge callback reads the restored content. - const recovery = await recoverInterruptedReplacement(absoluteFilePath).catch((error: unknown) => { + const recovery = await recoverInterruptedReplacement(resolvedTargetPath).catch((error: unknown) => { const code = getErrorCode(error) ?? "unknown" options?.trace?.({ stage: "recover", detail: `failed:${code}` }) throw error @@ -122,7 +357,7 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit if (options?.merge) { let existing: unknown = null try { - existing = JSON.parse(await fs.readFile(absoluteFilePath, "utf8")) + existing = JSON.parse(await fs.readFile(resolvedTargetPath, "utf8")) } catch (error: unknown) { const code = getErrorCode(error) if (!(error instanceof SyntaxError) && code !== "ENOENT") { @@ -135,18 +370,54 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // Step 1: Write data to a new temporary file and flush it to storage, // making a best-effort flush before committing the replacement. options?.trace?.({ stage: "write-start" }) - actualTempNewFilePath = createTempFilePath(absoluteFilePath, "new") + actualTempNewFilePath = createTempFilePath(resolvedTargetPath, "new") + + // Staging, the commit rename, the EPERM fallback's two renames and the rollback all take + // resolvedTargetPath - one resolved string for the whole publication. Staging beside the + // raw path when the target is a link's referent would make the commit rename cross + // filesystems, and mixing the two spellings is how a publish ends up beside the link + // it meant to replace. await _streamDataToFile(actualTempNewFilePath, data, options?.prettyPrint) + + // The bytes this write publishes identify the file a post-commit escape undo may + // remove. They are read after the staged file is written - before it there is nothing + // to read, and reading early failed with ENOENT on every confined write that reached + // the publish - and before the mode copy below, so a restrictive target mode cannot + // turn this read into a failure. A read failure aborts the write: publishing without + // the bytes would leave the undo unable to verify (and remove) an escaped file. + if (confinementRoot !== undefined) { + stagedBytes = await fs.readFile(actualTempNewFilePath) + } + + // CWE-732: the commit rename below lands the staged file onto the target, so the + // file that survives carries the staged file's mode, not the target's. A 0o600 + // target would otherwise be published 0o644 from the umask-derived default. The + // #1912 head (085fbf85e) carries this step for the same function; the blob main + // brought in does not, and without it the two resolutions differ on a permission + // property and the row that pins it can only pass on one platform. + await _copyTargetMode(resolvedTargetPath, actualTempNewFilePath) + await _flushFileToDisk(actualTempNewFilePath) + // A peer can replace an ancestor directory between the check above and the commit + // rename, and the rename takes a path: it replaces whatever file sits where it lands. + // Re-verify the destination here, as late as the publish allows, so an escaped commit + // is refused before it can overwrite bytes this write never read. The teardown below + // removes the staged file, so both files keep their own content. A swap that lands + // between this check and the rename is still caught fail-closed by the re-check after + // the commit. + if (confinementRoot !== undefined) { + const commitScopeRoot = await _resolveScopeRoot(confinementRoot) + _assertWithinScope(absoluteFilePath, await _resolveScopeRoot(resolvedTargetPath), commitScopeRoot) + } // Step 2: Commit the replacement with a single atomic rename. The // committed target stays in place until this rename lands, so a // process exit before or during the commit can no longer leave the // canonical path absent. try { options?.trace?.({ stage: "replacement-rename" }) - await fs.rename(actualTempNewFilePath, absoluteFilePath) + await fs.rename(actualTempNewFilePath, resolvedTargetPath) } catch (renameError: unknown) { if (getErrorCode(renameError) !== "EPERM") { throw renameError @@ -159,10 +430,10 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // second rename fails, and the recovery pass at the start of the // next write repairs a crash between the two renames. options?.trace?.({ stage: "backup-rename", detail: "eperm-fallback" }) - actualTempBackupFilePath = createTempFilePath(absoluteFilePath, "bak") - await fs.rename(absoluteFilePath, actualTempBackupFilePath) + actualTempBackupFilePath = createTempFilePath(resolvedTargetPath, "bak") + await fs.rename(resolvedTargetPath, actualTempBackupFilePath) options?.trace?.({ stage: "replacement-rename", detail: "eperm-fallback" }) - await fs.rename(actualTempNewFilePath, absoluteFilePath) + await fs.rename(actualTempNewFilePath, resolvedTargetPath) } // If we reach here, the new file is successfully in place. @@ -171,6 +442,32 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit actualTempNewFilePath = null options?.trace?.({ stage: "write-complete" }) + // Fail-closed confinement re-check. The check above decides the target as it + // resolves at check time; publication takes a path and re-resolves the tree + // at commit time, so an ancestor directory replaced by a link inside that + // window would publish outside the declared scope. Re-resolve after the + // commit: if the bytes landed outside, undo by removing exactly the file + // this write published at the escaped location (never a same-named file a peer + // placed there after the commit) and report the escape. The peer's swap itself is + // left as the peer made it. The re-check above, taken before the commit rename, + // refuses a swapped ancestor as soon as the write reaches it, so this one is the + // backstop for the sliver that is left: a swap that lands between that check and + // the rename still publishes outside the scope, the rename still replaces whatever + // file sits where it lands, and the undo below removes our bytes without being + // able to give back a peer's content the rename already consumed. + if (confinementRoot !== undefined) { + const publishedPath = await _resolveScopeRoot(resolvedTargetPath) + const scopeRoot = await _resolveScopeRoot(confinementRoot) + try { + _assertWithinScope(absoluteFilePath, publishedPath, scopeRoot) + } catch (escapeError) { + // Undo only the file this write published, never a same-named file a peer + // placed there after the commit. + await undoEscapedPublish(publishedPath, stagedBytes) + throw escapeError + } + } + // Step 3: If a backup was created, attempt to delete it. if (actualTempBackupFilePath) { try { @@ -187,7 +484,41 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit } } } catch (originalError) { - console.error(`Operation failed for ${absoluteFilePath}: [Original Error Caught]`, originalError) + console.error( + `Operation failed for ${resolvedTargetPath ?? absoluteFilePath}: [Original Error Caught]`, + originalError, + ) // A confinement escape is reported as the escape, not as whatever the teardown + // surfaced: re-resolve the publish target, and if the committed bytes landed outside + // the declared scope, remove exactly the file this write published there and report + // ConfinedPathEscapeError. undoEscapedPublish compares the staged bytes first, so a + // peer's file at the same name - including a backup this rollback just restored - + // is left alone. Errors that are not an escape keep their own type. + if (confinementRoot !== undefined && resolvedTargetPath !== undefined) { + // This re-check runs while the write is already failing, so it must not decide what the + // teardown does. Both locals stay undefined until their resolution lands, which is what + // separates a scope that cannot be canonicalized from a target that escaped the scope. + let publishedPath: string | undefined + let scopeRoot: string | undefined + try { + publishedPath = await _resolveScopeRoot(resolvedTargetPath) + scopeRoot = await _resolveScopeRoot(confinementRoot) + _assertWithinScope(absoluteFilePath, publishedPath, scopeRoot) + } catch (checkError) { + if (publishedPath !== undefined && scopeRoot !== undefined) { + // The check ran and said escape: undo exactly this write's bytes and report the + // escape, as before. + await undoEscapedPublish(publishedPath, stagedBytes) + throw checkError + } + // The scope could not be canonicalized at all. Report it and keep going, so the + // rollback and the staged cleanup below still run and the failure the caller sees + // stays the one this catch block was entered with. + console.error( + `Confinement re-check for ${absoluteFilePath} could not run during the teardown:`, + checkError, + ) + } + } const newFileToCleanupWithinCatch = actualTempNewFilePath const backupFileToRollbackOrCleanupWithinCatch = actualTempBackupFilePath @@ -195,7 +526,10 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // Attempt rollback if a backup was made if (backupFileToRollbackOrCleanupWithinCatch) { try { - await fs.rename(backupFileToRollbackOrCleanupWithinCatch, absoluteFilePath) + // A backup only ever exists once the resolved target is fixed, so the fallback is + // for the type, not for a reachable case; naming it here keeps the rollback and the + // commit rename on the same resolved string. + await fs.rename(backupFileToRollbackOrCleanupWithinCatch, resolvedTargetPath ?? absoluteFilePath) // Mark as handled, prevent later unlink of this path actualTempBackupFilePath = null } catch (rollbackError) { @@ -212,10 +546,16 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit try { await fs.unlink(newFileToCleanupWithinCatch) } catch (cleanupError) { - console.error( - `[Catch] Failed to clean up temporary new file ${newFileToCleanupWithinCatch}:`, - cleanupError, - ) + // The staged file is often already gone: the commit rename consumed it, or an + // earlier teardown removed it. Finding it absent is the expected outcome of a + // failed publish, not a second failure, so it is not logged as one. Any other + // cleanup failure is still reported. + if (getErrorCode(cleanupError) !== "ENOENT") { + console.error( + `[Catch] Failed to clean up temporary new file ${newFileToCleanupWithinCatch}:`, + cleanupError, + ) + } } } @@ -230,7 +570,7 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit await releaseLock() } catch (unlockError) { // Do not re-throw here, as the originalError from the try/catch (if any) is more important. - console.error(`Failed to release lock for ${absoluteFilePath}:`, unlockError) + console.error(`Failed to release lock for ${resolvedTargetPath ?? absoluteFilePath}:`, unlockError) } } } @@ -264,7 +604,33 @@ async function _streamDataToFile(targetPath: string, data: unknown, prettyPrint } /** - * Flushes a fully written temp file to storage before it is committed. + * Copies the existing target's permission mode onto the staged file so the publish + * does not silently widen it. A missing target has no mode to copy; a stat or chmod + * that fails for another reason is logged and the write proceeds with the staged + * file's own mode, because the replacement protocol - not the mode - is what makes the + * write atomic. + */ +async function _copyTargetMode(targetPath: string, stagedPath: string): Promise { + let mode: number + try { + const stats = await fs.stat(targetPath) + mode = stats.mode & 0o777 + } catch (statError: unknown) { + const code = getErrorCode(statError) + if (code && code !== "ENOENT" && code !== "ENOTDIR") { + console.error(`Could not read the mode of ${targetPath} before publishing onto it:`, statError) + } + return + } + try { + await fs.chmod(stagedPath, mode) + } catch (chmodError: unknown) { + console.error(`Failed to copy mode ${mode.toString(8)} from ${targetPath} onto ${stagedPath}:`, chmodError) + } +} + +/** + * Syncs the directory that holds a freshly committed file. * Best effort: durability against power loss is a bonus here, process-crash * safety comes from the rename protocol itself, and a filesystem that * refuses fsync must not block the write.