fix: use safeWriteJson for all JSON file writes

[KJ7LNW]

Context

This PR introduces safeWriteJson utility and refactors all direct JSON file writes across the codebase to use it, preventing potential data corruption during write operations.

Implementation

The new safeWriteJson utility provides:

• Atomic write operations using a temporary file approach
• Backup creation before overwriting existing files
• Proper error handling and cleanup of temporary files
• Protection against concurrent writes to the same file
• Support for custom JSON formatting with optional replacer and space arguments

All direct JSON file writes have been refactored to use this utility, including:

• Configuration files
• Settings export/import
• Task persistence
• File context tracking

This change ensures all JSON writes throughout the application are safe from corruption due to:

• Application crashes during writes
• Power failures
• Concurrent modification attempts

Fixes: #722

How to Test

• Run the test suites to verify all tests pass
• Verify settings can be exported and imported correctly
• Check that configuration files are properly saved

Get in Touch

Discord: KJ7LNW

---

Important

Introduces safeWriteJson utility for atomic JSON writes, replacing direct writes in key modules to enhance data integrity and error handling.

• Behavior:
  • Introduces safeWriteJson utility for atomic JSON file writes with backup and error handling.
  • Replaces direct JSON writes with safeWriteJson in modelCache.ts, modelEndpointCache.ts, and importExport.ts.
  • Handles application crashes, power failures, and concurrent writes.
• Testing:
  • Adds tests for safeWriteJson in safeWriteJson.test.ts to cover success and failure scenarios.
  • Mocks safeWriteJson in cache-manager.test.ts and McpHub.test.ts to verify integration.
• Dependencies:
  • Adds proper-lockfile and stream-json to package.json for file locking and streaming.

^{This description was created by for 4c88c21. You can customize this summary. It will automatically update as commits are pushed.}

[KJ7LNW]

Note to reviewer:

src/utils/safeWriteJson.ts is the primary implementation. everything else is just testing and simple 1-line replacements like this to hook it into place:

			if (!exists) {
-				await fs.writeFile(mcpPath, JSON.stringify({ mcpServers: {} }, null, 2))
+				await safeWriteJson(mcpPath, { mcpServers: {} })
			}

Note that ..., null, 2 is the default so it is not passed, however those options are still available for pass-through.

[daniel-lxs]

Hey, @KJ7LNW, thank you for the contribution!. Do you think we should remove the console logs? Could this implementation have high impact in performance?

[KJ7LNW]

Do you think we should remove the console logs? Could this implementation have high impact in performance?

• logs: yes
• errors: no - should errors throw, or just log? The problem with throwing is I do not know if these are handled further up the stack and I want this to be as resilient as possible (especially in the possible case that blank screen crashes are caused by on handled throws, but that is speculation).

My preference is always to throw errors, but not at the cost of crashing the application especially if the error is transient because the next write will successfully complete because this implementation is idempotent .

In any event the errors should also include back traces, so we can figure out the cause if it happens

I am switching to draft mode until logs are cleaned up

[KJ7LNW]

@daniel-lxs I have applied your suggestions, rebased, and all tests are passing.

[ellipsis-dev]

The rollback error handling block is comprehensive but complex; splitting into helper functions may improve readability and testability.

[daniel-lxs]

All of the suggestions were addressed, it might be worth considering if the new rule should be added or not.

LGTM

[mrubens]

Nice!

[KJ7LNW]

See also #4468