maestro-flow 0.1.0

package/dashboard/dist-server/server/sse/sse-hub.js

@@ -0,0 +1,112 @@
+import { DEFAULT_CONFIG } from '../../shared/constants.js';
+// ---------------------------------------------------------------------------
+// SSEHub — manages connected SSE clients and broadcasts EventBus events
+// ---------------------------------------------------------------------------
+export class SSEHub {
+    eventBus;
+    clients = new Map();
+    maxConnections;
+    heartbeatMs;
+    heartbeatTimer = null;
+    nextId = 0;
+    eventListener;
+    constructor(eventBus, options) {
+        this.eventBus = eventBus;
+        this.maxConnections = options?.maxConnections ?? DEFAULT_CONFIG.sseMaxConnections;
+        this.heartbeatMs = options?.heartbeatMs ?? DEFAULT_CONFIG.sseHeartbeatMs;
+        // Subscribe to all EventBus events and broadcast to clients
+        this.eventListener = (event) => {
+            if (this.clients.size === 0)
+                return;
+            this.broadcast(event.type, event.data);
+        };
+        this.eventBus.onAny(this.eventListener);
+        this.startHeartbeat();
+    }
+    /**
+     * Check if a new client can be accepted.
+     * Returns false when max connections is reached.
+     */
+    canAccept() {
+        return this.clients.size < this.maxConnections;
+    }
+    /**
+     * Register a new SSE client.
+     * Returns the client ID for later removal, or null if max connections reached.
+     */
+    addClient(write, close) {
+        if (!this.canAccept()) {
+            return null;
+        }
+        const id = `sse-${++this.nextId}`;
+        this.clients.set(id, { id, write, close });
+        return id;
+    }
+    /** Unregister a client by ID */
+    removeClient(id) {
+        this.clients.delete(id);
+    }
+    /** Return the number of connected clients */
+    getClientCount() {
+        return this.clients.size;
+    }
+    /** Send a named SSE event to all connected clients */
+    broadcast(eventType, data) {
+        if (this.clients.size === 0)
+            return;
+        const payload = formatSSE(eventType, data);
+        const toRemove = [];
+        for (const [id, client] of this.clients) {
+            try {
+                client.write(payload);
+            }
+            catch {
+                toRemove.push(id);
+            }
+        }
+        // Clean up failed clients
+        for (const id of toRemove) {
+            this.clients.delete(id);
+        }
+    }
+    /** Stop heartbeat and unsubscribe from EventBus */
+    destroy() {
+        if (this.heartbeatTimer !== null) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.eventBus.offAny(this.eventListener);
+        this.clients.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+    startHeartbeat() {
+        this.heartbeatTimer = setInterval(() => {
+            if (this.clients.size === 0)
+                return;
+            const comment = ': heartbeat\n\n';
+            const toRemove = [];
+            for (const [id, client] of this.clients) {
+                try {
+                    client.write(comment);
+                }
+                catch {
+                    toRemove.push(id);
+                }
+            }
+            for (const id of toRemove) {
+                this.clients.delete(id);
+            }
+        }, this.heartbeatMs);
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Format data as an SSE message: `event: <type>\ndata: <json>\n\n` */
+function formatSSE(eventType, data) {
+    const json = JSON.stringify(data);
+    return `event: ${eventType}\ndata: ${json}\n\n`;
+}
+//# sourceMappingURL=sse-hub.js.map

package/dashboard/dist-server/server/sse/sse-hub.js.map

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

package/dashboard/dist-server/server/sse/sse-hub.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dashboard/dist-server/server/sse/sse-hub.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { SSEHub } from './sse-hub.js';
+import { DashboardEventBus } from '../state/event-bus.js';
+describe('SSEHub', () => {
+    let eventBus;
+    let hub;
+    beforeEach(() => {
+        vi.useFakeTimers();
+        eventBus = new DashboardEventBus();
+        hub = new SSEHub(eventBus, { maxConnections: 3, heartbeatMs: 1000 });
+    });
+    afterEach(() => {
+        hub.destroy();
+        vi.useRealTimers();
+    });
+    describe('addClient / removeClient', () => {
+        it('adds a client and returns an id', () => {
+            const id = hub.addClient(vi.fn(), vi.fn());
+            expect(id).toMatch(/^sse-/);
+            expect(hub.getClientCount()).toBe(1);
+        });
+        it('returns null when max connections reached', () => {
+            hub.addClient(vi.fn(), vi.fn());
+            hub.addClient(vi.fn(), vi.fn());
+            hub.addClient(vi.fn(), vi.fn());
+            expect(hub.getClientCount()).toBe(3);
+            const id = hub.addClient(vi.fn(), vi.fn());
+            expect(id).toBeNull();
+            expect(hub.getClientCount()).toBe(3);
+        });
+        it('removes a client by id', () => {
+            const id = hub.addClient(vi.fn(), vi.fn());
+            expect(hub.getClientCount()).toBe(1);
+            hub.removeClient(id);
+            expect(hub.getClientCount()).toBe(0);
+        });
+        it('removing a non-existent client is a no-op', () => {
+            hub.removeClient('sse-nonexistent');
+            expect(hub.getClientCount()).toBe(0);
+        });
+    });
+    describe('canAccept', () => {
+        it('returns true when under max', () => {
+            expect(hub.canAccept()).toBe(true);
+        });
+        it('returns false when at max', () => {
+            hub.addClient(vi.fn(), vi.fn());
+            hub.addClient(vi.fn(), vi.fn());
+            hub.addClient(vi.fn(), vi.fn());
+            expect(hub.canAccept()).toBe(false);
+        });
+    });
+    describe('broadcast', () => {
+        it('sends formatted SSE to all connected clients', () => {
+            const write1 = vi.fn();
+            const write2 = vi.fn();
+            hub.addClient(write1, vi.fn());
+            hub.addClient(write2, vi.fn());
+            hub.broadcast('test:event', { foo: 'bar' });
+            const expected = 'event: test:event\ndata: {"foo":"bar"}\n\n';
+            expect(write1).toHaveBeenCalledWith(expected);
+            expect(write2).toHaveBeenCalledWith(expected);
+        });
+        it('removes clients that throw on write', () => {
+            const failWrite = vi.fn().mockImplementation(() => {
+                throw new Error('connection reset');
+            });
+            const goodWrite = vi.fn();
+            hub.addClient(failWrite, vi.fn());
+            hub.addClient(goodWrite, vi.fn());
+            hub.broadcast('test:event', { data: 1 });
+            expect(hub.getClientCount()).toBe(1);
+            expect(goodWrite).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('EventBus integration', () => {
+        it('broadcasts EventBus events to SSE clients', () => {
+            const write = vi.fn();
+            hub.addClient(write, vi.fn());
+            eventBus.emit('heartbeat', null);
+            expect(write).toHaveBeenCalledTimes(1);
+            const payload = write.mock.calls[0][0];
+            expect(payload).toContain('event: heartbeat');
+        });
+    });
+    describe('heartbeat', () => {
+        it('sends heartbeat comments to all clients on interval', () => {
+            const write = vi.fn();
+            hub.addClient(write, vi.fn());
+            vi.advanceTimersByTime(1000);
+            expect(write).toHaveBeenCalledWith(': heartbeat\n\n');
+        });
+        it('removes clients that fail during heartbeat', () => {
+            const failWrite = vi.fn().mockImplementation(() => {
+                throw new Error('broken pipe');
+            });
+            hub.addClient(failWrite, vi.fn());
+            expect(hub.getClientCount()).toBe(1);
+            vi.advanceTimersByTime(1000);
+            expect(hub.getClientCount()).toBe(0);
+        });
+    });
+    describe('destroy', () => {
+        it('clears all clients and stops heartbeat', () => {
+            const write = vi.fn();
+            hub.addClient(write, vi.fn());
+            hub.addClient(vi.fn(), vi.fn());
+            expect(hub.getClientCount()).toBe(2);
+            hub.destroy();
+            expect(hub.getClientCount()).toBe(0);
+            // Heartbeat should no longer fire
+            vi.advanceTimersByTime(5000);
+            expect(write).not.toHaveBeenCalledWith(': heartbeat\n\n');
+        });
+        it('unsubscribes from EventBus', () => {
+            const write = vi.fn();
+            hub.addClient(write, vi.fn());
+            hub.destroy();
+            // Re-add a client to the now-destroyed hub (it won't receive events)
+            // Events emitted after destroy should not reach old listeners
+            eventBus.emit('heartbeat', null);
+            // write was only called 0 times (no events forwarded after destroy + clients cleared)
+            // The client was cleared, so even if listener fires there's no one to write to
+            expect(hub.getClientCount()).toBe(0);
+        });
+    });
+});
+//# sourceMappingURL=sse-hub.test.js.map

package/dashboard/dist-server/server/sse/sse-hub.test.js.map

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

package/dashboard/dist-server/server/state/event-bus.d.ts

@@ -0,0 +1,97 @@
+import type { SSEEvent, SSEEventType, BoardState, PhaseCard, TaskCard, ScratchCard, ProjectState } from '../../shared/types.js';
+import type { AgentProcess, NormalizedEntry, ApprovalRequest, AgentStatusPayload, AgentStoppedPayload, AgentTurnCompletedPayload } from '../../shared/agent-types.js';
+import type { SupervisorStatus } from '../../shared/execution-types.js';
+import type { LearningStats } from '../../shared/learning-types.js';
+import type { ScheduledTask } from '../../shared/schedule-types.js';
+import type { ExtensionInfo } from '../../shared/extension-types.js';
+import type { CommanderState, Decision, CommanderConfig, AssessMetrics } from '../../shared/commander-types.js';
+import type { CoordinateStatusPayload, CoordinateStepPayload, CoordinateAnalysisPayload, CoordinateClarificationPayload } from '../../shared/coordinate-types.js';
+import type { RequirementProgressPayload, RequirementExpandedPayload, RequirementCommittedPayload } from '../../shared/requirement-types.js';
+import type { ExecutionStartedPayload, ExecutionCompletedPayload, ExecutionFailedPayload } from '../../shared/ws-protocol.js';
+export interface DashboardEventMap {
+    'board:full': BoardState;
+    'phase:updated': PhaseCard;
+    'task:updated': TaskCard;
+    'scratch:updated': ScratchCard;
+    'project:updated': ProjectState;
+    'watcher:error': string;
+    'heartbeat': null;
+    'connected': null;
+    'agent:spawned': AgentProcess;
+    'agent:entry': NormalizedEntry;
+    'agent:approval': ApprovalRequest;
+    'agent:status': AgentStatusPayload;
+    'agent:stopped': AgentStoppedPayload;
+    'agent:turnCompleted': AgentTurnCompletedPayload;
+    'execution:started': ExecutionStartedPayload;
+    'execution:completed': ExecutionCompletedPayload;
+    'execution:failed': ExecutionFailedPayload;
+    'execution:scheduler_status': SupervisorStatus;
+    'supervisor:status': SupervisorStatus;
+    'supervisor:learning_update': LearningStats;
+    'supervisor:schedule_triggered': {
+        taskId: string;
+        taskName: string;
+        taskType: string;
+    };
+    'supervisor:schedule_update': {
+        tasks: ScheduledTask[];
+    };
+    'supervisor:extension_loaded': {
+        extensions: ExtensionInfo[];
+    };
+    'supervisor:extension_error': {
+        name: string;
+        error: string;
+    };
+    'commander:status': CommanderState;
+    'commander:tick': CommanderState;
+    'commander:decision': Decision;
+    'commander:config': CommanderConfig;
+    'commander:assess_metrics': AssessMetrics;
+    'commander:error': {
+        error: string;
+        context: string;
+        timestamp: number;
+    };
+    'coordinate:status': CoordinateStatusPayload;
+    'coordinate:step': CoordinateStepPayload;
+    'coordinate:analysis': CoordinateAnalysisPayload;
+    'coordinate:clarification_needed': CoordinateClarificationPayload;
+    'coordinate:analyze_metrics': AssessMetrics;
+    'coordinate:error': {
+        error: string;
+        context: string;
+        step: number;
+        timestamp: number;
+    };
+    'requirement:expanded': RequirementExpandedPayload;
+    'requirement:refined': RequirementExpandedPayload;
+    'requirement:committed': RequirementCommittedPayload;
+    'requirement:progress': RequirementProgressPayload;
+    'workspace:switched': {
+        workspace: string;
+    };
+}
+export declare class DashboardEventBus {
+    private readonly emitter;
+    private readonly ringBuffer;
+    private readonly maxBufferSize;
+    constructor();
+    /** Emit a typed dashboard event */
+    emit<K extends SSEEventType & keyof DashboardEventMap>(type: K, data: DashboardEventMap[K]): void;
+    /** Get recent events from the ring buffer, optionally filtered by type prefix */
+    getRecentEvents(limit?: number, typePrefix?: string): SSEEvent[];
+    /** Get current ring buffer size */
+    getBufferSize(): number;
+    /** Subscribe to a specific event type */
+    on<K extends SSEEventType & keyof DashboardEventMap>(type: K, listener: (event: SSEEvent) => void): void;
+    /** Unsubscribe from a specific event type */
+    off<K extends SSEEventType & keyof DashboardEventMap>(type: K, listener: (event: SSEEvent) => void): void;
+    /** Subscribe to all event types */
+    onAny(listener: (event: SSEEvent) => void): void;
+    /** Unsubscribe from all event types */
+    offAny(listener: (event: SSEEvent) => void): void;
+    /** Remove all listeners */
+    removeAllListeners(): void;
+}

package/dashboard/dist-server/server/state/event-bus.js

@@ -0,0 +1,110 @@
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// All event types — single source of truth for onAny / offAny
+// ---------------------------------------------------------------------------
+const ALL_EVENT_TYPES = [
+    'board:full',
+    'phase:updated',
+    'task:updated',
+    'scratch:updated',
+    'project:updated',
+    'watcher:error',
+    'heartbeat',
+    'connected',
+    'agent:spawned',
+    'agent:entry',
+    'agent:approval',
+    'agent:status',
+    'agent:stopped',
+    'agent:turnCompleted',
+    'execution:started',
+    'execution:completed',
+    'execution:failed',
+    'execution:scheduler_status',
+    'supervisor:status',
+    'supervisor:learning_update',
+    'supervisor:schedule_triggered',
+    'supervisor:schedule_update',
+    'supervisor:extension_loaded',
+    'supervisor:extension_error',
+    'commander:status',
+    'commander:tick',
+    'commander:decision',
+    'commander:config',
+    'commander:assess_metrics',
+    'commander:error',
+    'coordinate:status',
+    'coordinate:analyze_metrics',
+    'coordinate:step',
+    'coordinate:analysis',
+    'coordinate:clarification_needed',
+    'coordinate:error',
+    'requirement:expanded',
+    'requirement:refined',
+    'requirement:committed',
+    'requirement:progress',
+    'workspace:switched',
+];
+// ---------------------------------------------------------------------------
+// Typed event bus wrapping Node.js EventEmitter
+// ---------------------------------------------------------------------------
+export class DashboardEventBus {
+    emitter = new EventEmitter();
+    ringBuffer = [];
+    maxBufferSize = 1000;
+    constructor() {
+        // Raise limit — multiple SSE clients may subscribe
+        this.emitter.setMaxListeners(50);
+    }
+    /** Emit a typed dashboard event */
+    emit(type, data) {
+        const event = {
+            type,
+            data,
+            timestamp: new Date().toISOString(),
+        };
+        this.emitter.emit(type, event);
+        // Append to ring buffer for audit trail
+        this.ringBuffer.push(event);
+        if (this.ringBuffer.length > this.maxBufferSize) {
+            this.ringBuffer.shift();
+        }
+    }
+    /** Get recent events from the ring buffer, optionally filtered by type prefix */
+    getRecentEvents(limit = 100, typePrefix) {
+        let events = this.ringBuffer;
+        if (typePrefix) {
+            events = events.filter((e) => e.type.startsWith(typePrefix));
+        }
+        return events.slice(-limit);
+    }
+    /** Get current ring buffer size */
+    getBufferSize() {
+        return this.ringBuffer.length;
+    }
+    /** Subscribe to a specific event type */
+    on(type, listener) {
+        this.emitter.on(type, listener);
+    }
+    /** Unsubscribe from a specific event type */
+    off(type, listener) {
+        this.emitter.off(type, listener);
+    }
+    /** Subscribe to all event types */
+    onAny(listener) {
+        for (const type of ALL_EVENT_TYPES) {
+            this.emitter.on(type, listener);
+        }
+    }
+    /** Unsubscribe from all event types */
+    offAny(listener) {
+        for (const type of ALL_EVENT_TYPES) {
+            this.emitter.off(type, listener);
+        }
+    }
+    /** Remove all listeners */
+    removeAllListeners() {
+        this.emitter.removeAllListeners();
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dashboard/dist-server/server/state/event-bus.js.map

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

package/dashboard/dist-server/server/state/file-reader.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read and parse a JSON file with retry logic.
+ *
+ * - Returns `null` when the file does not exist (ENOENT).
+ * - Retries up to 3 times with 100ms delay on JSON parse errors,
+ *   which can occur when another process is mid-write.
+ * - Throws after max retries on persistent parse failure.
+ */
+export declare function readJsonSafe<T>(filePath: string): Promise<T | null>;

package/dashboard/dist-server/server/state/file-reader.js

@@ -0,0 +1,54 @@
+import { readFile } from 'node:fs/promises';
+// ---------------------------------------------------------------------------
+// Safe JSON file reader with retry logic
+// ---------------------------------------------------------------------------
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 100;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Read and parse a JSON file with retry logic.
+ *
+ * - Returns `null` when the file does not exist (ENOENT).
+ * - Retries up to 3 times with 100ms delay on JSON parse errors,
+ *   which can occur when another process is mid-write.
+ * - Throws after max retries on persistent parse failure.
+ */
+export async function readJsonSafe(filePath) {
+    let lastError;
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const raw = await readFile(filePath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            // File does not exist — not an error, just absent
+            if (isEnoent(err)) {
+                return null;
+            }
+            lastError = err;
+            // Only retry on parse errors (partial write); not on permission errors etc.
+            if (err instanceof SyntaxError && attempt < MAX_RETRIES) {
+                await delay(RETRY_DELAY_MS);
+                continue;
+            }
+            // Non-parse filesystem error — throw immediately
+            if (!(err instanceof SyntaxError)) {
+                throw err;
+            }
+        }
+    }
+    // Exhausted retries on parse error
+    throw new Error(`Failed to parse JSON from ${filePath} after ${MAX_RETRIES} attempts: ${String(lastError)}`);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isEnoent(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'code' in err &&
+        err.code === 'ENOENT');
+}
+//# sourceMappingURL=file-reader.js.map

package/dashboard/dist-server/server/state/file-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-reader.js","sourceRoot":"","sources":["../../../src/server/state/file-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,8EAA8E;AAC9E,yCAAyC;AACzC,8EAA8E;AAE9E,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,QAAgB;IACpD,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,kDAAkD;YAClD,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,OAAO,IAAI,CAAC;YACd,CAAC;YAED,SAAS,GAAG,GAAG,CAAC;YAEhB,4EAA4E;YAC5E,IAAI,GAAG,YAAY,WAAW,IAAI,OAAO,GAAG,WAAW,EAAE,CAAC;gBACxD,MAAM,KAAK,CAAC,cAAc,CAAC,CAAC;gBAC5B,SAAS;YACX,CAAC;YAED,iDAAiD;YACjD,IAAI,CAAC,CAAC,GAAG,YAAY,WAAW,CAAC,EAAE,CAAC;gBAClC,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IAED,mCAAmC;IACnC,MAAM,IAAI,KAAK,CACb,6BAA6B,QAAQ,UAAU,WAAW,cAAc,MAAM,CAAC,SAAS,CAAC,EAAE,CAC5F,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,QAAQ,CAAC,GAAY;IAC5B,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACZ,GAAwB,CAAC,IAAI,KAAK,QAAQ,CAC5C,CAAC;AACJ,CAAC"}

package/dashboard/dist-server/server/state/fs-watcher.d.ts

@@ -0,0 +1,19 @@
+import type { StateManager } from './state-manager.js';
+import type { DashboardEventBus } from './event-bus.js';
+export declare class FSWatcher {
+    private readonly workflowRoot;
+    private readonly stateManager;
+    private readonly eventBus;
+    private readonly debounceMs;
+    private watcher;
+    private rebuildTimer;
+    /** Per-file debounce timers keyed by absolute path */
+    private debounceTimers;
+    constructor(workflowRoot: string, stateManager: StateManager, eventBus: DashboardEventBus, debounceMs?: number);
+    /** Start watching .workflow/ for relevant file changes */
+    start(): void;
+    /** Stop watching and clean up */
+    stop(): Promise<void>;
+    private handleChange;
+    private scheduleFullRebuild;
+}

package/dashboard/dist-server/server/state/fs-watcher.js

@@ -0,0 +1,94 @@
+import { watch } from 'chokidar';
+import { SSE_EVENT_TYPES } from '../../shared/constants.js';
+// ---------------------------------------------------------------------------
+// FSWatcher — chokidar-based file watcher for .workflow/ directory
+// ---------------------------------------------------------------------------
+const REBUILD_DELAY_MS = 5_000;
+export class FSWatcher {
+    workflowRoot;
+    stateManager;
+    eventBus;
+    debounceMs;
+    watcher = null;
+    rebuildTimer = null;
+    /** Per-file debounce timers keyed by absolute path */
+    debounceTimers = new Map();
+    constructor(workflowRoot, stateManager, eventBus, debounceMs = 150) {
+        this.workflowRoot = workflowRoot;
+        this.stateManager = stateManager;
+        this.eventBus = eventBus;
+        this.debounceMs = debounceMs;
+    }
+    /** Start watching .workflow/ for relevant file changes */
+    start() {
+        if (this.watcher)
+            return;
+        const patterns = [
+            `${this.workflowRoot}/state.json`,
+            `${this.workflowRoot}/phases/*/index.json`,
+            `${this.workflowRoot}/phases/*/.task/TASK-*.json`,
+            `${this.workflowRoot}/scratch/*/index.json`,
+        ];
+        this.watcher = watch(patterns, {
+            ignoreInitial: true,
+            persistent: true,
+            // Use polling on Windows as fallback for reliability
+            usePolling: process.platform === 'win32',
+            interval: 200,
+        });
+        this.watcher.on('add', (path) => this.handleChange(path));
+        this.watcher.on('change', (path) => this.handleChange(path));
+        this.watcher.on('unlink', (path) => this.handleChange(path));
+        this.watcher.on('error', (error) => {
+            console.error('FSWatcher error:', error);
+            this.eventBus.emit(SSE_EVENT_TYPES.WATCHER_ERROR, String(error));
+            this.scheduleFullRebuild();
+        });
+    }
+    /** Stop watching and clean up */
+    async stop() {
+        // Clear all debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        if (this.rebuildTimer) {
+            clearTimeout(this.rebuildTimer);
+            this.rebuildTimer = null;
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal
+    // -------------------------------------------------------------------------
+    handleChange(filePath) {
+        // Per-file debounce: reset timer on each event for the same file
+        const existing = this.debounceTimers.get(filePath);
+        if (existing) {
+            clearTimeout(existing);
+        }
+        const timer = setTimeout(() => {
+            this.debounceTimers.delete(filePath);
+            this.stateManager.applyFileChange(filePath).catch((err) => {
+                console.error(`Failed to apply file change for ${filePath}:`, err);
+                this.scheduleFullRebuild();
+            });
+        }, this.debounceMs);
+        this.debounceTimers.set(filePath, timer);
+    }
+    scheduleFullRebuild() {
+        // Avoid stacking rebuild timers
+        if (this.rebuildTimer)
+            return;
+        this.rebuildTimer = setTimeout(() => {
+            this.rebuildTimer = null;
+            this.stateManager.buildInitialState().catch((err) => {
+                console.error('Full state rebuild failed:', err);
+            });
+        }, REBUILD_DELAY_MS);
+    }
+}
+//# sourceMappingURL=fs-watcher.js.map