feat: implement file-based locking mechanism for multi-instance coordination

Author: ErcinDedeoglu

src/data/state.ts

@@ -4,9 +4,10 @@
  * Persists and loads local sync state and configuration.
  */
 
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, rename, unlink } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
+import { dirname } from 'node:path';
 import type { SyncConfig, LocalSyncState, PathConfig } from '../types/index.js';
 import { DEFAULT_CONFIG } from '../types/index.js';
 
@@ -74,11 +75,10 @@ export function getTokenSource(): 'config' | 'env' | 'none' {
 }
 
 /**
- * Save plugin configuration to disk.
+ * Save plugin configuration to disk (atomic write).
  */
 export async function saveConfig(pathConfig: PathConfig, config: SyncConfig): Promise<void> {
-  await ensureDir(pathConfig.configDir);
-  await writeFile(pathConfig.pluginConfigPath, JSON.stringify(config, null, 2), 'utf-8');
+  await atomicWriteFile(pathConfig.pluginConfigPath, JSON.stringify(config, null, 2));
 }
 
 /**
@@ -94,11 +94,10 @@ export async function loadLocalState(pathConfig: PathConfig): Promise<LocalSyncS
 }
 
 /**
- * Save local sync state to disk.
+ * Save local sync state to disk (atomic write).
  */
 export async function saveLocalState(pathConfig: PathConfig, state: LocalSyncState): Promise<void> {
-  await ensureDir(pathConfig.dataDir);
-  await writeFile(pathConfig.localStatePath, JSON.stringify(state, null, 2), 'utf-8');
+  await atomicWriteFile(pathConfig.localStatePath, JSON.stringify(state, null, 2));
 }
 
 /**
@@ -140,3 +139,25 @@ export function createInitialConfig(token: string, defaults: typeof DEFAULT_CONF
 async function ensureDir(dirPath: string): Promise<void> {
   await mkdir(dirPath, { recursive: true });
 }
+
+/**
+ * Atomically write a file using write-to-temp-then-rename pattern.
+ * This prevents partial writes from corrupting files when multiple
+ * processes write simultaneously.
+ */
+async function atomicWriteFile(filePath: string, content: string): Promise<void> {
+  const tempPath = `${filePath}.${String(process.pid)}.tmp`;
+  await ensureDir(dirname(filePath));
+  try {
+    await writeFile(tempPath, content, 'utf-8');
+    await rename(tempPath, filePath);
+  } catch (error) {
+    // Clean up temp file on error
+    try {
+      await unlink(tempPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw error;
+  }
+}

src/plugin/state-manager.ts

@@ -6,7 +6,7 @@
 
 import type { PathConfig } from '../types/paths.js';
 import { DEFAULT_CONFIG, type SyncConfig, type SyncCategory } from '../types/index.js';
-import { SyncEngine } from '../sync/engine/index.js';
+import { SyncEngine, type SyncEngineOptions } from '../sync/engine/index.js';
 import { RepoStorageBackend, type RepoClientConfig } from '../storage/index.js';
 import { createFileWatcher } from '../sync/watcher/index.js';
 import { loadConfig, saveConfig, loadLocalState, generateMachineId } from '../data/index.js';
@@ -19,6 +19,7 @@ const state: PluginState = createInitialState();
  * Initialize the plugin state from disk.
  */
 export async function initializeState(pathConfig: PathConfig): Promise<void> {
+  state.pathConfig = pathConfig;
   state.config = await loadConfig(pathConfig);
   state.localState = await loadLocalState(pathConfig);
 }
@@ -50,22 +51,21 @@ export function initializeEngine(): void {
   // Support key rotation: oldEncryptionKey from config is used as fallback for decryption
   const oldKey = state.oldPassphrase ?? state.config.oldEncryptionKey;
 
-  state.engine = new SyncEngine(
-    oldKey
-      ? {
-          config: state.config,
-          backend,
-          localState: state.localState,
-          passphrase: state.passphrase ?? undefined,
-          oldPassphrase: oldKey,
-        }
-      : {
-          config: state.config,
-          backend,
-          localState: state.localState,
-          passphrase: state.passphrase ?? undefined,
-        }
-  );
+  // Build engine options, conditionally adding optional properties
+  const engineOptions: SyncEngineOptions = {
+    config: state.config,
+    backend,
+    localState: state.localState,
+    passphrase: state.passphrase ?? undefined,
+  };
+  if (oldKey) {
+    engineOptions.oldPassphrase = oldKey;
+  }
+  if (state.pathConfig?.lockPath) {
+    engineOptions.lockPath = state.pathConfig.lockPath;
+  }
+
+  state.engine = new SyncEngine(engineOptions);
 
   state.isInitialized = true;
 }

src/plugin/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { SyncConfig, LocalSyncState } from '../types/index.js';
+import type { PathConfig } from '../types/paths.js';
 import type { SyncEngine } from '../sync/engine/index.js';
 import type { FileWatcher } from '../sync/watcher/index.js';
 
@@ -17,6 +18,8 @@ export interface PluginState {
   /** Previous encryption key for key rotation */
   oldPassphrase: string | null;
   isInitialized: boolean;
+  /** Path configuration for lock file and other paths */
+  pathConfig: PathConfig | null;
 }
 
 export function createInitialState(): PluginState {
@@ -28,5 +31,6 @@ export function createInitialState(): PluginState {
     passphrase: null,
     oldPassphrase: null,
     isInitialized: false,
+    pathConfig: null,
   };
 }

src/sync/engine/result.ts

@@ -62,6 +62,13 @@ export function buildNoChangeResult(): SyncResult {
   return { success: true, action: 'no-change', message: 'Already in sync' };
 }
 
+/**
+ * Build a skipped result (e.g., when another instance holds the lock).
+ */
+export function buildSkippedResult(reason: string): SyncResult {
+  return { success: true, action: 'no-change', message: `Skipped: ${reason}` };
+}
+
 /**
  * Convert an unknown error to SyncResult.
  */

src/sync/engine/sync-engine.ts

@@ -24,9 +24,11 @@ import {
   buildConflictResult,
   buildErrorResult,
   buildNoChangeResult,
+  buildSkippedResult,
   handleSyncError,
 } from './result.js';
 import { checkMaxRetries, calculateBackoff, sleep } from './retry.js';
+import { acquireLock, releaseLock, getLockHolder } from '../local-lock.js';
 
 export { type CategoryData };
 
@@ -36,13 +38,15 @@ export class SyncEngine {
   private localState: LocalSyncState | null;
   private readonly passphrase: string | undefined;
   private readonly oldPassphrase: string | undefined;
+  private readonly lockPath: string | undefined;
 
   constructor(options: SyncEngineOptions) {
     this.backend = options.backend;
     this.config = options.config;
     this.localState = options.localState;
     this.passphrase = options.passphrase;
     this.oldPassphrase = options.oldPassphrase;
+    this.lockPath = options.lockPath;
   }
 
   /** Get crypto options for encryption/decryption with key rotation support */
@@ -55,10 +59,19 @@ export class SyncEngine {
 
   public async sync(localData: CategoryData[]): Promise<SyncResult> {
     if (!this.hasStorageConfigured()) return buildErrorResult('No storage configured');
+
+    // Acquire local lock to prevent concurrent syncs on same machine
+    if (this.lockPath && !acquireLock(this.lockPath, 'sync')) {
+      const holder = getLockHolder(this.lockPath);
+      return buildSkippedResult(`Another instance is syncing${holder ? ` (${holder})` : ''}`);
+    }
+
     try {
       return await this.performSync(localData);
     } catch (error) {
       return handleSyncError(error);
+    } finally {
+      if (this.lockPath) releaseLock(this.lockPath);
     }
   }
 

src/sync/engine/types.ts

@@ -15,6 +15,8 @@ export interface SyncEngineOptions {
   passphrase: string | undefined;
   /** Previous encryption key for key rotation */
   oldPassphrase?: string;
+  /** Lock file path for multi-instance coordination */
+  lockPath?: string;
 }
 
 /** Get crypto options from engine options */