conductor-bridge 1.0.0

package/dist/sync/watcher.js

@@ -0,0 +1,281 @@
+/**
+ * File Watcher Daemon
+ *
+ * Watches .conductor/ directory for changes and triggers auto-sync.
+ * Provides real-time bidirectional state synchronization.
+ */
+import { watch } from 'chokidar';
+import { join, basename } from 'path';
+import { EventEmitter } from 'events';
+import { syncConductorToUSD, syncUSDToConductor, computeFileChecksum, hasFileChanged, } from './state-sync.js';
+import { ConductorConvergenceTracker } from './convergence-tracker.js';
+import { parsePlan } from '../parsers/plan-parser.js';
+import { parseState } from '../parsers/state-parser.js';
+import { readFile } from 'fs/promises';
+import { withFallback } from '../utils/error-handling.js';
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_CONFIG = {
+    debounceMs: 500,
+    syncOnStart: true,
+    watchPatterns: [
+        '**/spec.md',
+        '**/plan.md',
+        '**/state.md',
+        '**/amendments/*.md',
+    ],
+    ignorePatterns: [
+        '**/node_modules/**',
+        '**/.git/**',
+        '**/dispatch.md',
+    ],
+};
+// ============================================================================
+// Watcher Class
+// ============================================================================
+export class ConductorWatcher extends EventEmitter {
+    config;
+    watcher = null;
+    checksums = new Map();
+    debounceTimer = null;
+    stats;
+    convergenceTracker;
+    isRunning = false;
+    constructor(config) {
+        super();
+        this.config = {
+            conductorDir: config.conductorDir || '.conductor',
+            cognitiveStatePath: config.cognitiveStatePath || '.conductor/cognitive_state.json',
+            autoSave: config.autoSave ?? true,
+            autoSaveIntervalMs: config.autoSaveIntervalMs ?? 300000, // 5 min
+            debounceMs: config.debounceMs ?? DEFAULT_CONFIG.debounceMs,
+            syncOnStart: config.syncOnStart ?? DEFAULT_CONFIG.syncOnStart,
+            watchPatterns: config.watchPatterns ?? DEFAULT_CONFIG.watchPatterns,
+            ignorePatterns: config.ignorePatterns ?? DEFAULT_CONFIG.ignorePatterns,
+        };
+        this.stats = {
+            startTime: new Date(),
+            syncCount: 0,
+            lastSyncTime: null,
+            lastSyncResult: null,
+            errors: [],
+            exchangeCount: 0,
+        };
+        this.convergenceTracker = new ConductorConvergenceTracker();
+    }
+    /**
+     * Start watching for file changes.
+     */
+    async start() {
+        if (this.isRunning) {
+            return;
+        }
+        this.stats.startTime = new Date();
+        this.isRunning = true;
+        // Initialize file watcher
+        this.watcher = watch(this.config.watchPatterns, {
+            cwd: this.config.conductorDir,
+            ignored: this.config.ignorePatterns,
+            persistent: true,
+            ignoreInitial: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 100,
+                pollInterval: 50,
+            },
+        });
+        // Set up event handlers
+        this.watcher.on('change', (path) => this.handleChange(path));
+        this.watcher.on('add', (path) => this.handleChange(path));
+        this.watcher.on('error', (error) => this.handleError(error));
+        // Initial sync
+        if (this.config.syncOnStart) {
+            await this.sync();
+        }
+        // Initial checksum capture
+        await this.captureChecksums();
+        this.emit('started', { config: this.config });
+        console.log(`[Watcher] Started watching ${this.config.conductorDir}`);
+    }
+    /**
+     * Stop watching for file changes.
+     */
+    async stop() {
+        if (!this.isRunning) {
+            return;
+        }
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+        this.isRunning = false;
+        this.emit('stopped', { stats: this.stats });
+        console.log('[Watcher] Stopped');
+    }
+    /**
+     * Handle file change event.
+     */
+    handleChange(path) {
+        const filename = basename(path);
+        this.emit('change', { path, filename });
+        // Debounce sync
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.onDebouncedChange(path);
+        }, this.config.debounceMs);
+    }
+    /**
+     * Handle debounced file change.
+     */
+    async onDebouncedChange(path) {
+        const filename = basename(path);
+        const fullPath = join(this.config.conductorDir, path);
+        try {
+            // Check if file actually changed (via checksum)
+            const newChecksum = await computeFileChecksum(fullPath);
+            const oldChecksum = this.checksums.get(path) || '';
+            if (!hasFileChanged(newChecksum, oldChecksum)) {
+                return;
+            }
+            // Update checksum
+            this.checksums.set(path, newChecksum);
+            // Determine sync direction based on changed file
+            if (filename === 'plan.md' || filename === 'state.md') {
+                // Conductor changed → sync to USD
+                await this.syncWithConvergence();
+            }
+            else if (filename === 'cognitive_state.json') {
+                // USD changed → sync to Conductor
+                const result = await syncUSDToConductor(this.config);
+                this.recordSyncResult(result);
+            }
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Perform sync with convergence tracking.
+     */
+    async syncWithConvergence() {
+        try {
+            // Read current state with proper error logging
+            const statePath = join(this.config.conductorDir, 'state.md');
+            const stateContent = await withFallback(() => readFile(statePath, 'utf-8'), '', { operation: 'readStateFile', path: statePath });
+            const stateResult = parseState(stateContent);
+            if (!stateResult.success || !stateResult.data) {
+                await this.sync();
+                return;
+            }
+            const planPath = join(this.config.conductorDir, stateResult.data.frontmatter.plan || 'plan.md');
+            const planContent = await withFallback(() => readFile(planPath, 'utf-8'), '', { operation: 'readPlanFile', path: planPath });
+            const planResult = parsePlan(planContent);
+            if (!planResult.success || !planResult.data) {
+                await this.sync();
+                return;
+            }
+            // Track convergence
+            this.stats.exchangeCount++;
+            const convergence = this.convergenceTracker.recordExchange(planResult.data);
+            this.emit('convergence', {
+                xi_n: convergence.xi_n,
+                attractor: convergence.attractor,
+                stability: convergence.stability,
+                glyph: this.convergenceTracker.getGlyph(),
+                isConverged: convergence.isConverged,
+            });
+            // Perform sync
+            await this.sync();
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Perform bidirectional sync.
+     */
+    async sync() {
+        const result = await syncConductorToUSD(this.config);
+        this.recordSyncResult(result);
+        return result;
+    }
+    /**
+     * Record sync result in stats.
+     */
+    recordSyncResult(result) {
+        this.stats.syncCount++;
+        this.stats.lastSyncTime = new Date();
+        this.stats.lastSyncResult = result;
+        if (!result.success) {
+            this.stats.errors.push(...result.warnings);
+        }
+        this.emit('sync', result);
+    }
+    /**
+     * Handle errors.
+     */
+    handleError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.stats.errors.push(message);
+        this.emit('error', { message, timestamp: new Date().toISOString() });
+        console.error(`[Watcher] Error: ${message}`);
+    }
+    /**
+     * Capture initial file checksums.
+     */
+    async captureChecksums() {
+        const files = ['state.md', 'plan.md', 'spec.md'];
+        for (const file of files) {
+            try {
+                const fullPath = join(this.config.conductorDir, file);
+                const checksum = await computeFileChecksum(fullPath);
+                if (checksum) {
+                    this.checksums.set(file, checksum);
+                }
+            }
+            catch {
+                // File doesn't exist, ignore
+            }
+        }
+    }
+    /**
+     * Get current stats.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Get convergence glyph.
+     */
+    getConvergenceGlyph() {
+        return this.convergenceTracker.getGlyph();
+    }
+    /**
+     * Check if watcher is running.
+     */
+    isActive() {
+        return this.isRunning;
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create and start a conductor watcher.
+ */
+export async function createWatcher(conductorDir, options) {
+    const watcher = new ConductorWatcher({
+        conductorDir,
+        cognitiveStatePath: join(conductorDir, 'cognitive_state.json'),
+        ...options,
+    });
+    await watcher.start();
+    return watcher;
+}
+//# sourceMappingURL=watcher.js.map

package/dist/sync/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/sync/watcher.ts"],"names":[],"mappings":"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"}

package/dist/utils/atomic-write.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Atomic Write Utility
+ *
+ * Provides atomic file writes using temp file + rename pattern.
+ * This ensures file integrity even during crashes or power failures.
+ */
+export interface AtomicWriteOptions {
+    /** File encoding (default: 'utf-8') */
+    encoding?: BufferEncoding;
+    /** Temp file suffix (default: '.tmp') */
+    tempSuffix?: string;
+    /** Whether to fsync after write (default: true) */
+    fsync?: boolean;
+}
+/**
+ * Write file atomically using temp file + rename pattern.
+ *
+ * On POSIX systems, rename() is atomic within the same filesystem.
+ * On Windows, we unlink the target first if it exists (not fully atomic
+ * but prevents data corruption).
+ *
+ * @param filePath - Target file path
+ * @param data - Data to write
+ * @param options - Write options
+ */
+export declare function atomicWriteFile(filePath: string, data: string | Buffer, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Check if a file exists
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/utils/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../../src/utils/atomic-write.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE"}

package/dist/utils/atomic-write.js

@@ -0,0 +1,69 @@
+/**
+ * Atomic Write Utility
+ *
+ * Provides atomic file writes using temp file + rename pattern.
+ * This ensures file integrity even during crashes or power failures.
+ */
+import { writeFile, rename, unlink, stat, mkdir } from 'fs/promises';
+import { join, dirname, basename } from 'path';
+import { randomBytes } from 'crypto';
+/**
+ * Write file atomically using temp file + rename pattern.
+ *
+ * On POSIX systems, rename() is atomic within the same filesystem.
+ * On Windows, we unlink the target first if it exists (not fully atomic
+ * but prevents data corruption).
+ *
+ * @param filePath - Target file path
+ * @param data - Data to write
+ * @param options - Write options
+ */
+export async function atomicWriteFile(filePath, data, options = {}) {
+    const { encoding = 'utf-8', tempSuffix = '.tmp', } = options;
+    // Generate unique temp file name to avoid collisions
+    const uniqueId = randomBytes(6).toString('hex');
+    const tempPath = join(dirname(filePath), `.${basename(filePath)}.${uniqueId}${tempSuffix}`);
+    try {
+        // Ensure parent directory exists
+        await mkdir(dirname(filePath), { recursive: true });
+        // Write to temp file
+        await writeFile(tempPath, data, { encoding });
+        // On Windows, rename fails if target exists, so unlink first
+        if (process.platform === 'win32') {
+            try {
+                await unlink(filePath);
+            }
+            catch (err) {
+                // File doesn't exist, that's fine
+                if (err.code !== 'ENOENT') {
+                    throw err;
+                }
+            }
+        }
+        // Rename temp to target (atomic on most filesystems)
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        // Clean up temp file on failure
+        try {
+            await unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}
+/**
+ * Check if a file exists
+ */
+export async function fileExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/utils/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../../src/utils/atomic-write.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAWrC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,IAAqB,EACrB,UAA8B,EAAE;IAEhC,MAAM,EACJ,QAAQ,GAAG,OAAO,EAClB,UAAU,GAAG,MAAM,GACpB,GAAG,OAAO,CAAC;IAEZ,qDAAqD;IACrD,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CACnB,OAAO,CAAC,QAAQ,CAAC,EACjB,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,UAAU,EAAE,CAClD,CAAC;IAEF,IAAI,CAAC;QACH,iCAAiC;QACjC,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEpD,qBAAqB;QACrB,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QAE9C,6DAA6D;QAC7D,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,kCAAkC;gBAClC,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACrD,MAAM,GAAG,CAAC;gBACZ,CAAC;YACH,CAAC;QACH,CAAC;QAED,qDAAqD;QACrD,MAAM,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gCAAgC;QAChC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/utils/error-handling.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Error Handling Utility
+ *
+ * Provides structured error handling with logging before fallbacks.
+ * Replaces silent .catch(() => '') patterns with logged fallbacks.
+ */
+export interface FallbackContext {
+    /** Name of the operation that failed */
+    operation: string;
+    /** File path or other identifier */
+    path?: string;
+    /** Additional context */
+    details?: Record<string, unknown>;
+}
+export interface FallbackOptions {
+    /** Whether to log warnings (default: true) */
+    logWarning?: boolean;
+    /** Custom logger function */
+    logger?: (message: string, context: FallbackContext, error: unknown) => void;
+    /** Whether to include stack trace in logs (default: false in production) */
+    includeStack?: boolean;
+}
+/**
+ * Execute an async operation with a fallback value, logging errors before fallback.
+ *
+ * This replaces patterns like:
+ * ```ts
+ * const content = await readFile(path).catch(() => '');
+ * ```
+ *
+ * With structured error handling:
+ * ```ts
+ * const content = await withFallback(
+ *   () => readFile(path, 'utf-8'),
+ *   '',
+ *   { operation: 'readStateFile', path }
+ * );
+ * ```
+ *
+ * @param operation - Async operation to execute
+ * @param fallback - Value to return if operation fails
+ * @param context - Context for logging
+ * @param options - Options for error handling
+ * @returns Result of operation or fallback value
+ */
+export declare function withFallback<T>(operation: () => Promise<T>, fallback: T, context: FallbackContext, options?: FallbackOptions): Promise<T>;
+/**
+ * Synchronous version of withFallback.
+ */
+export declare function withFallbackSync<T>(operation: () => T, fallback: T, context: FallbackContext, options?: FallbackOptions): T;
+/**
+ * Execute an operation with retry logic and exponential backoff.
+ *
+ * @param operation - Async operation to execute
+ * @param context - Context for logging
+ * @param maxRetries - Maximum number of retries (default: 3)
+ * @param baseDelayMs - Base delay between retries in ms (default: 100)
+ * @returns Result of operation
+ * @throws Last error if all retries fail
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, context: FallbackContext, maxRetries?: number, baseDelayMs?: number): Promise<T>;
+/**
+ * Create a logged fallback wrapper for a specific operation.
+ *
+ * @param operationName - Name of the operation
+ * @param fallbackValue - Default fallback value
+ * @returns A function that wraps operations with logging
+ */
+export declare function createFallbackWrapper<T>(operationName: string, fallbackValue: T): (operation: () => Promise<T>, path?: string) => Promise<T>;
+//# sourceMappingURL=error-handling.d.ts.map

package/dist/utils/error-handling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling.d.ts","sourceRoot":"","sources":["../../src/utils/error-handling.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7E,4EAA4E;IAC5E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAcD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,SAAS,EAAE,MAAM,CAAC,EAClB,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,eAAoB,GAC5B,CAAC,CAWH;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,eAAe,EACxB,UAAU,GAAE,MAAU,EACtB,WAAW,GAAE,MAAY,GACxB,OAAO,CAAC,CAAC,CAAC,CAqBZ;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,CAAC,GACf,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAO5D"}

package/dist/utils/error-handling.js

@@ -0,0 +1,109 @@
+/**
+ * Error Handling Utility
+ *
+ * Provides structured error handling with logging before fallbacks.
+ * Replaces silent .catch(() => '') patterns with logged fallbacks.
+ */
+const defaultLogger = (message, context, error) => {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.warn(`[${context.operation}] ${message}: ${errorMessage}`, {
+        path: context.path,
+        ...context.details,
+    });
+};
+/**
+ * Execute an async operation with a fallback value, logging errors before fallback.
+ *
+ * This replaces patterns like:
+ * ```ts
+ * const content = await readFile(path).catch(() => '');
+ * ```
+ *
+ * With structured error handling:
+ * ```ts
+ * const content = await withFallback(
+ *   () => readFile(path, 'utf-8'),
+ *   '',
+ *   { operation: 'readStateFile', path }
+ * );
+ * ```
+ *
+ * @param operation - Async operation to execute
+ * @param fallback - Value to return if operation fails
+ * @param context - Context for logging
+ * @param options - Options for error handling
+ * @returns Result of operation or fallback value
+ */
+export async function withFallback(operation, fallback, context, options = {}) {
+    const { logWarning = true, logger = defaultLogger } = options;
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (logWarning) {
+            logger('Operation failed, using fallback', context, error);
+        }
+        return fallback;
+    }
+}
+/**
+ * Synchronous version of withFallback.
+ */
+export function withFallbackSync(operation, fallback, context, options = {}) {
+    const { logWarning = true, logger = defaultLogger } = options;
+    try {
+        return operation();
+    }
+    catch (error) {
+        if (logWarning) {
+            logger('Operation failed, using fallback', context, error);
+        }
+        return fallback;
+    }
+}
+/**
+ * Execute an operation with retry logic and exponential backoff.
+ *
+ * @param operation - Async operation to execute
+ * @param context - Context for logging
+ * @param maxRetries - Maximum number of retries (default: 3)
+ * @param baseDelayMs - Base delay between retries in ms (default: 100)
+ * @returns Result of operation
+ * @throws Last error if all retries fail
+ */
+export async function withRetry(operation, context, maxRetries = 3, baseDelayMs = 100) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < maxRetries) {
+                const delay = baseDelayMs * Math.pow(2, attempt);
+                console.warn(`[${context.operation}] Attempt ${attempt + 1} failed, retrying in ${delay}ms...`, { path: context.path, error: error instanceof Error ? error.message : String(error) });
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Create a logged fallback wrapper for a specific operation.
+ *
+ * @param operationName - Name of the operation
+ * @param fallbackValue - Default fallback value
+ * @returns A function that wraps operations with logging
+ */
+export function createFallbackWrapper(operationName, fallbackValue) {
+    return async (operation, path) => {
+        return withFallback(operation, fallbackValue, {
+            operation: operationName,
+            path,
+        });
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=error-handling.js.map

package/dist/utils/error-handling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling.js","sourceRoot":"","sources":["../../src/utils/error-handling.ts"],"names":[],"mappings":"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"}

package/dist/utils/file-lock.d.ts

@@ -0,0 +1,46 @@
+/**
+ * File Lock Utility
+ *
+ * Provides cross-platform file locking with retry logic.
+ * Uses proper-lockfile for reliable locking behavior.
+ */
+export interface LockOptions {
+    /** Maximum time to wait for lock (ms) */
+    timeout?: number;
+    /** Time between retry attempts (ms) */
+    retryInterval?: number;
+    /** Maximum number of retries */
+    maxRetries?: number;
+    /** Stale lock timeout (ms) - locks older than this are considered stale */
+    stale?: number;
+}
+export declare class FileLockError extends Error {
+    readonly filePath: string;
+    readonly code: 'ELOCKED' | 'ETIMEOUT' | 'EUNLOCK';
+    constructor(message: string, filePath: string, code: 'ELOCKED' | 'ETIMEOUT' | 'EUNLOCK');
+}
+/**
+ * Acquire a lock on a file, execute an operation, then release the lock.
+ *
+ * @param filePath - Path to the file to lock
+ * @param operation - Async operation to perform while holding the lock
+ * @param options - Lock options
+ * @returns Result of the operation
+ *
+ * @example
+ * ```ts
+ * const result = await withFileLock('/path/to/file.json', async () => {
+ *   const data = await readFile('/path/to/file.json', 'utf-8');
+ *   const parsed = JSON.parse(data);
+ *   parsed.count++;
+ *   await writeFile('/path/to/file.json', JSON.stringify(parsed));
+ *   return parsed;
+ * });
+ * ```
+ */
+export declare function withFileLock<T>(filePath: string, operation: () => Promise<T>, options?: LockOptions): Promise<T>;
+/**
+ * Check if a file is currently locked.
+ */
+export declare function isFileLocked(filePath: string): boolean;
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/utils/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../../src/utils/file-lock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAYD,qBAAa,aAAc,SAAQ,KAAK;aAGpB,QAAQ,EAAE,MAAM;aAChB,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS;gBAFxD,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS;CAK3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,CAAC,CAAC,CA2EZ;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGtD"}