🤖 refactor: make ExtensionMetadataService stateless with atomic writes

Redesigned ExtensionMetadataService to be stateless and use atomic writes.
Created reusable atomic write utilities to centralize write-file-atomic usage.

Changes:
- Created src/utils/atomicWrite.ts with writeFileAtomically() and writeFileAtomicallySync()
- ExtensionMetadataService now uses load-modify-save pattern (no in-memory state)
- All read methods now async (load from disk each time)
- All write methods use atomic writes via writeFileAtomically()
- Simplified IpcMain to use regular constructor + initialize() method
- Updated Config.ts to use new writeFileAtomicallySync() utility

Benefits:
- Stateless: no stale data, always fresh from disk
- Atomic writes: prevents corruption from crashes/concurrent writes
- Reusable: atomic write logic centralized for use across codebase
- Simpler: no cache invalidation or state management needed

Trade-offs:
- Slightly higher disk I/O (acceptable for read-heavy workload)
- Simplicity and correctness over performance optimization

Author: ammar-agent

src/bench/headlessEnvironment.ts

@@ -104,7 +104,8 @@ export async function createHeadlessEnvironment(
   const mockIpcMainModule = mockedElectron.ipcMain;
   const mockIpcRendererModule = mockedElectron.ipcRenderer;
 
-  const ipcMain = await IpcMain.create(config);
+  const ipcMain = new IpcMain(config);
+  await ipcMain.initialize();
   ipcMain.register(mockIpcMainModule, mockWindow);
 
   const dispose = async () => {

src/config.ts

@@ -3,12 +3,12 @@ import * as path from "path";
 import * as os from "os";
 import * as crypto from "crypto";
 import * as jsonc from "jsonc-parser";
-import writeFileAtomic from "write-file-atomic";
 import type { WorkspaceMetadata, FrontendWorkspaceMetadata } from "./types/workspace";
 import type { Secret, SecretsConfig } from "./types/secrets";
 import type { Workspace, ProjectConfig, ProjectsConfig } from "./types/project";
 import type { RuntimeConfig } from "./types/runtime";
 import { DEFAULT_RUNTIME_CONFIG } from "./constants/workspace";
+import { writeFileAtomicallySync } from "./utils/atomicWrite";
 
 // Re-export project types from dedicated types file (for preload usage)
 export type { Workspace, ProjectConfig, ProjectsConfig };
@@ -81,7 +81,7 @@ export class Config {
         projects: Array.from(config.projects.entries()),
       };
 
-      writeFileAtomic.sync(this.configFile, JSON.stringify(data, null, 2));
+      writeFileAtomicallySync(this.configFile, JSON.stringify(data, null, 2));
     } catch (error) {
       console.error("Error saving config:", error);
     }
@@ -485,7 +485,7 @@ ${jsonString}`;
         fs.mkdirSync(this.rootDir, { recursive: true });
       }
 
-      writeFileAtomic.sync(this.secretsFile, JSON.stringify(config, null, 2));
+      writeFileAtomicallySync(this.secretsFile, JSON.stringify(config, null, 2));
     } catch (error) {
       console.error("Error saving secrets config:", error);
       throw error;

src/main-desktop.ts

@@ -315,7 +315,8 @@ async function loadServices(): Promise<void> {
   ]);
   /* eslint-enable no-restricted-syntax */
   config = new ConfigClass();
-  ipcMain = await IpcMainClass.create(config);
+  ipcMain = new IpcMainClass(config);
+  await ipcMain.initialize();
 
   loadTokenizerModules().catch((error) => {
     console.error("Failed to preload tokenizer modules:", error);

src/main-server.ts

@@ -145,7 +145,8 @@ const httpIpcMain = new HttpIpcMainAdapter(app);
 (async () => {
   // Initialize config and IPC service
   const config = new Config();
-  const ipcMainService = await IpcMain.create(config);
+  const ipcMainService = new IpcMain(config);
+  await ipcMainService.initialize();
 
   // Register IPC handlers
   ipcMainService.register(

src/services/ExtensionMetadataService.ts

@@ -1,14 +1,15 @@
 import { dirname } from "path";
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { mkdir, readFile } from "fs/promises";
 import { existsSync } from "fs";
 import {
   type ExtensionMetadata,
   type ExtensionMetadataFile,
   getExtensionMetadataPath,
 } from "@/utils/extensionMetadata";
+import { writeFileAtomically } from "@/utils/atomicWrite";
 
 /**
- * Service for managing workspace metadata used by VS Code extension integration.
+ * Stateless service for managing workspace metadata used by VS Code extension integration.
  * 
  * This service tracks:
  * - recency: Unix timestamp (ms) of last user interaction
@@ -17,8 +18,10 @@ import {
  * 
  * File location: ~/.cmux/extensionMetadata.json
  * 
- * Uses atomic writes to prevent corruption. Read-heavy workload (extension reads,
- * main app writes on user interactions).
+ * Design:
+ * - Stateless: reads from disk on every operation, no in-memory cache
+ * - Atomic writes: uses write-file-atomic to prevent corruption
+ * - Read-heavy workload: extension reads, main app writes on user interactions
  */
 
 export interface WorkspaceMetadata extends ExtensionMetadata {
@@ -28,44 +31,33 @@ export interface WorkspaceMetadata extends ExtensionMetadata {
 
 export class ExtensionMetadataService {
   private readonly filePath: string;
-  private data: ExtensionMetadataFile;
 
-  private constructor(filePath: string, data: ExtensionMetadataFile) {
-    this.filePath = filePath;
-    this.data = data;
+  constructor(filePath?: string) {
+    this.filePath = filePath ?? getExtensionMetadataPath();
   }
 
   /**
-   * Create a new ExtensionMetadataService instance.
-   * Use this static factory method instead of the constructor.
+   * Initialize the service by ensuring directory exists and clearing stale streaming flags.
+   * Call this once on app startup.
    */
-  static async create(filePath?: string): Promise<ExtensionMetadataService> {
-    const path = filePath ?? getExtensionMetadataPath();
-
+  async initialize(): Promise<void> {
     // Ensure directory exists
-    const dir = dirname(path);
+    const dir = dirname(this.filePath);
     if (!existsSync(dir)) {
       await mkdir(dir, { recursive: true });
     }
 
-    // Load existing data or initialize
-    const data = await ExtensionMetadataService.loadData(path);
-
-    const service = new ExtensionMetadataService(path, data);
-
     // Clear stale streaming flags (from crashes)
-    await service.clearStaleStreaming();
-
-    return service;
+    await this.clearStaleStreaming();
   }
 
-  private static async loadData(filePath: string): Promise<ExtensionMetadataFile> {
-    if (!existsSync(filePath)) {
+  private async load(): Promise<ExtensionMetadataFile> {
+    if (!existsSync(this.filePath)) {
       return { version: 1, workspaces: {} };
     }
 
     try {
-      const content = await readFile(filePath, "utf-8");
+      const content = await readFile(this.filePath, "utf-8");
       const parsed = JSON.parse(content) as ExtensionMetadataFile;
 
       // Validate structure
@@ -83,10 +75,10 @@ export class ExtensionMetadataService {
     }
   }
 
-  private async save(): Promise<void> {
+  private async save(data: ExtensionMetadataFile): Promise<void> {
     try {
-      const content = JSON.stringify(this.data, null, 2);
-      await writeFile(this.filePath, content, "utf-8");
+      const content = JSON.stringify(data, null, 2);
+      await writeFileAtomically(this.filePath, content);
     } catch (error) {
       console.error("[ExtensionMetadataService] Failed to save metadata:", error);
     }
@@ -97,44 +89,51 @@ export class ExtensionMetadataService {
    * Call this on user messages or other interactions.
    */
   async updateRecency(workspaceId: string, timestamp: number = Date.now()): Promise<void> {
-    if (!this.data.workspaces[workspaceId]) {
-      this.data.workspaces[workspaceId] = {
+    const data = await this.load();
+    
+    if (!data.workspaces[workspaceId]) {
+      data.workspaces[workspaceId] = {
         recency: timestamp,
         streaming: false,
         lastModel: null,
       };
     } else {
-      this.data.workspaces[workspaceId].recency = timestamp;
+      data.workspaces[workspaceId].recency = timestamp;
     }
-    await this.save();
+    
+    await this.save(data);
   }
 
   /**
    * Set the streaming status for a workspace.
    * Call this when streams start/end.
    */
   async setStreaming(workspaceId: string, streaming: boolean, model?: string): Promise<void> {
+    const data = await this.load();
     const now = Date.now();
-    if (!this.data.workspaces[workspaceId]) {
-      this.data.workspaces[workspaceId] = {
+    
+    if (!data.workspaces[workspaceId]) {
+      data.workspaces[workspaceId] = {
         recency: now,
         streaming,
         lastModel: model ?? null,
       };
     } else {
-      this.data.workspaces[workspaceId].streaming = streaming;
+      data.workspaces[workspaceId].streaming = streaming;
       if (model) {
-        this.data.workspaces[workspaceId].lastModel = model;
+        data.workspaces[workspaceId].lastModel = model;
       }
     }
-    await this.save();
+    
+    await this.save(data);
   }
 
   /**
    * Get metadata for a single workspace.
    */
-  getMetadata(workspaceId: string): WorkspaceMetadata | null {
-    const entry = this.data.workspaces[workspaceId];
+  async getMetadata(workspaceId: string): Promise<WorkspaceMetadata | null> {
+    const data = await this.load();
+    const entry = data.workspaces[workspaceId];
     if (!entry) return null;
 
     return {
@@ -148,11 +147,12 @@ export class ExtensionMetadataService {
    * Get all workspace metadata, ordered by recency.
    * Used by VS Code extension to sort workspace list.
    */
-  getAllMetadata(): Map<string, WorkspaceMetadata> {
+  async getAllMetadata(): Promise<Map<string, WorkspaceMetadata>> {
+    const data = await this.load();
     const map = new Map<string, WorkspaceMetadata>();
 
     // Convert to array, sort by recency, then create map
-    const entries = Object.entries(this.data.workspaces);
+    const entries = Object.entries(data.workspaces);
     entries.sort((a, b) => b[1].recency - a[1].recency);
 
     for (const [workspaceId, entry] of entries) {
@@ -171,9 +171,11 @@ export class ExtensionMetadataService {
    * Call this when a workspace is deleted.
    */
   async deleteWorkspace(workspaceId: string): Promise<void> {
-    if (this.data.workspaces[workspaceId]) {
-      delete this.data.workspaces[workspaceId];
-      await this.save();
+    const data = await this.load();
+    
+    if (data.workspaces[workspaceId]) {
+      delete data.workspaces[workspaceId];
+      await this.save(data);
     }
   }
 
@@ -182,15 +184,18 @@ export class ExtensionMetadataService {
    * Call this on app startup to clean up stale streaming states from crashes.
    */
   async clearStaleStreaming(): Promise<void> {
+    const data = await this.load();
     let modified = false;
-    for (const entry of Object.values(this.data.workspaces)) {
+    
+    for (const entry of Object.values(data.workspaces)) {
       if (entry.streaming) {
         entry.streaming = false;
         modified = true;
       }
     }
+    
     if (modified) {
-      await this.save();
+      await this.save(data);
     }
   }
 }

src/services/ipcMain.ts

@@ -59,44 +59,29 @@ export class IpcMain {
 
   private registered = false;
 
-  private constructor(
-    config: Config,
-    historyService: HistoryService,
-    partialService: PartialService,
-    initStateManager: InitStateManager,
-    extensionMetadata: ExtensionMetadataService,
-    aiService: AIService
-  ) {
+  constructor(config: Config) {
     this.config = config;
-    this.historyService = historyService;
-    this.partialService = partialService;
-    this.initStateManager = initStateManager;
-    this.extensionMetadata = extensionMetadata;
-    this.aiService = aiService;
+    this.historyService = new HistoryService(config);
+    this.partialService = new PartialService(config, this.historyService);
+    this.initStateManager = new InitStateManager(config);
+    this.extensionMetadata = new ExtensionMetadataService();
+    this.aiService = new AIService(
+      config,
+      this.historyService,
+      this.partialService,
+      this.initStateManager
+    );
 
     // Listen to AIService events to update metadata
     this.setupMetadataListeners();
   }
 
   /**
-   * Create a new IpcMain instance.
-   * Use this static factory method instead of the constructor.
+   * Initialize the service. Call this after construction.
+   * This is separate from the constructor to support async initialization.
    */
-  static async create(config: Config): Promise<IpcMain> {
-    const historyService = new HistoryService(config);
-    const partialService = new PartialService(config, historyService);
-    const initStateManager = new InitStateManager(config);
-    const extensionMetadata = await ExtensionMetadataService.create();
-    const aiService = new AIService(config, historyService, partialService, initStateManager);
-
-    return new IpcMain(
-      config,
-      historyService,
-      partialService,
-      initStateManager,
-      extensionMetadata,
-      aiService
-    );
+  async initialize(): Promise<void> {
+    await this.extensionMetadata.initialize();
   }
 
   /**

src/utils/atomicWrite.ts

@@ -0,0 +1,17 @@
+import writeFileAtomic from "write-file-atomic";
+
+/**
+ * Atomically write data to a file (async).
+ * Uses write-file-atomic to ensure the file is never in a half-written state.
+ */
+export async function writeFileAtomically(filePath: string, data: string): Promise<void> {
+  await writeFileAtomic(filePath, data, "utf-8");
+}
+
+/**
+ * Atomically write data to a file (sync).
+ * Uses write-file-atomic to ensure the file is never in a half-written state.
+ */
+export function writeFileAtomicallySync(filePath: string, data: string): void {
+  writeFileAtomic.sync(filePath, data);
+}

tests/ipcMain/setup.ts

@@ -66,7 +66,8 @@ export async function createTestEnvironment(): Promise<TestEnvironment> {
   const mockIpcRendererModule = mocked.ipcRenderer;
 
   // Create IpcMain instance
-  const ipcMain = await IpcMain.create(config);
+  const ipcMain = new IpcMain(config);
+  await ipcMain.initialize();
 
   // Register handlers with mock ipcMain and window
   ipcMain.register(mockIpcMainModule, mockWindow);