@synergenius/flow-weaver 0.2.0

package/dist/mcp/auto-registration.js

@@ -0,0 +1,62 @@
+import { execSync } from 'child_process';
+import * as readline from 'readline';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+function defaultRegistrationDeps() {
+    return {
+        execCommand: async (cmd) => {
+            try {
+                const stdout = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+                return { stdout: stdout.trim(), exitCode: 0 };
+            }
+            catch {
+                return { stdout: '', exitCode: 1 };
+            }
+        },
+        prompt: (question) => new Promise((resolve) => {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+            rl.question(question, (answer) => {
+                rl.close();
+                resolve(answer.trim().toLowerCase());
+            });
+        }),
+        log: (msg) => process.stderr.write(msg + '\n'),
+        resolveCliPath: () => {
+            // import.meta.url works in ESM (tsx), __dirname works in CJS (built bundle)
+            try {
+                return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+            }
+            catch {
+                return path.resolve(__dirname, '..');
+            }
+        },
+    };
+}
+export async function offerClaudeRegistration(options, deps) {
+    const d = deps ?? defaultRegistrationDeps();
+    // 1. Detect Claude Code
+    const whichCmd = process.platform === 'win32' ? 'where claude' : 'which claude';
+    const whichResult = await d.execCommand(whichCmd);
+    if (whichResult.exitCode !== 0) {
+        d.log('Claude Code not found in PATH. Skipping auto-registration.');
+        return;
+    }
+    // 2. Check if already registered
+    const listResult = await d.execCommand('claude mcp list');
+    if (listResult.stdout.includes('flow-weaver')) {
+        d.log('Flow Weaver MCP server already registered in Claude Code.');
+        return;
+    }
+    // 3. Prompt user
+    const answer = await d.prompt('Claude Code detected. Register Flow Weaver MCP server? (y/N) ');
+    if (answer !== 'y' && answer !== 'yes') {
+        d.log('Skipped MCP server registration.');
+        return;
+    }
+    // 4. Register
+    const cliPath = d.resolveCliPath();
+    const cmd = `claude mcp add --scope project flow-weaver -- npx tsx ${cliPath}/index.ts mcp-server --stdio`;
+    await d.execCommand(cmd);
+    d.log('Registered Flow Weaver MCP server. Restart Claude Code to activate.');
+}
+//# sourceMappingURL=auto-registration.js.map

package/dist/mcp/editor-connection.d.ts

@@ -0,0 +1,50 @@
+import type { AckResponse, EditorConnectionOptions } from './types.js';
+import type { EventBuffer } from './event-buffer.js';
+/**
+ * Manages a WebSocket connection to the Flow Weaver editor via socket.io.
+ * Supports sending commands and batches with request/response correlation,
+ * and forwards incoming `fw:` and `integration:` events to an {@link EventBuffer}.
+ */
+export declare class EditorConnection {
+    private socket;
+    private serverUrl;
+    private buffer;
+    private ioFactory;
+    private ackTimeout;
+    /**
+     * @param serverUrl - The base URL of the editor WebSocket server.
+     * @param buffer - The event buffer to push incoming events into.
+     * @param options - Optional connection configuration (custom io factory, ack timeout).
+     */
+    constructor(serverUrl: string, buffer: EventBuffer, options?: EditorConnectionOptions);
+    /**
+     * Establishes a WebSocket connection to the editor's `/integrations` namespace.
+     * Cleans up any previous connection first. Incoming `fw:` and `integration:` events
+     * are automatically forwarded to the event buffer.
+     * @param log - Optional logging callback for connection lifecycle events.
+     */
+    connect(log?: (msg: string) => void): void;
+    /** Whether the socket is currently connected to the editor. */
+    get isConnected(): boolean;
+    /**
+     * Sends a single command to the editor and waits for an acknowledgement.
+     * Returns an error response if not connected or if the ack times out.
+     * @param action - The command action name (e.g. "get-state", "add-node").
+     * @param params - Parameters for the command.
+     * @returns The editor's acknowledgement response.
+     */
+    sendCommand(action: string, params: Record<string, unknown>): Promise<AckResponse>;
+    /**
+     * Sends a batch of commands to the editor as a single request and waits for acknowledgement.
+     * Returns an error response if not connected or if the ack times out.
+     * @param commands - Array of commands, each with an action name and optional params.
+     * @returns The editor's acknowledgement response for the entire batch.
+     */
+    sendBatch(commands: Array<{
+        action: string;
+        params?: Record<string, unknown>;
+    }>): Promise<AckResponse>;
+    /** Disconnects from the editor and releases the socket. */
+    disconnect(): void;
+}
+//# sourceMappingURL=editor-connection.d.ts.map

package/dist/mcp/editor-connection.js

@@ -0,0 +1,125 @@
+import { io as socketIO } from 'socket.io-client';
+/**
+ * Manages a WebSocket connection to the Flow Weaver editor via socket.io.
+ * Supports sending commands and batches with request/response correlation,
+ * and forwards incoming `fw:` and `integration:` events to an {@link EventBuffer}.
+ */
+export class EditorConnection {
+    socket = null;
+    serverUrl;
+    buffer;
+    ioFactory;
+    ackTimeout;
+    /**
+     * @param serverUrl - The base URL of the editor WebSocket server.
+     * @param buffer - The event buffer to push incoming events into.
+     * @param options - Optional connection configuration (custom io factory, ack timeout).
+     */
+    constructor(serverUrl, buffer, options) {
+        this.serverUrl = serverUrl;
+        this.buffer = buffer;
+        this.ioFactory = options?.ioFactory ?? socketIO;
+        this.ackTimeout = options?.ackTimeout ?? 10_000;
+    }
+    /**
+     * Establishes a WebSocket connection to the editor's `/integrations` namespace.
+     * Cleans up any previous connection first. Incoming `fw:` and `integration:` events
+     * are automatically forwarded to the event buffer.
+     * @param log - Optional logging callback for connection lifecycle events.
+     */
+    connect(log) {
+        // Clean up previous connection to prevent duplicate listeners
+        if (this.socket) {
+            this.socket.removeAllListeners();
+            this.socket.disconnect();
+            this.socket = null;
+        }
+        // Write a startup event immediately so the hook file exists from the start
+        this.buffer.push('mcp:status', { status: 'connecting', server: this.serverUrl });
+        this.socket = this.ioFactory(`${this.serverUrl}/integrations`, {
+            query: { clientType: 'mcp' },
+            transports: ['websocket', 'polling'],
+            reconnection: true,
+            reconnectionDelay: 1000,
+            reconnectionAttempts: Infinity,
+        });
+        this.socket.on('connect', () => {
+            log?.(`Connected to editor at ${this.serverUrl}`);
+            this.buffer.push('mcp:status', { status: 'connected', server: this.serverUrl });
+        });
+        if (log) {
+            this.socket.on('disconnect', (reason) => log(`Disconnected from editor: ${reason}`));
+            this.socket.on('connect_error', (err) => log(`Editor connection error: ${err.message}`));
+        }
+        this.socket.onAny((event, data) => {
+            if (event.startsWith('fw:') || event.startsWith('integration:')) {
+                this.buffer.push(event, data);
+            }
+        });
+    }
+    /** Whether the socket is currently connected to the editor. */
+    get isConnected() {
+        return this.socket?.connected ?? false;
+    }
+    /**
+     * Sends a single command to the editor and waits for an acknowledgement.
+     * Returns an error response if not connected or if the ack times out.
+     * @param action - The command action name (e.g. "get-state", "add-node").
+     * @param params - Parameters for the command.
+     * @returns The editor's acknowledgement response.
+     */
+    async sendCommand(action, params) {
+        if (!this.socket) {
+            return { requestId: '', success: false, error: 'Not connected' };
+        }
+        const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        return new Promise((resolve) => {
+            const handler = (data) => {
+                if (data.requestId === requestId) {
+                    clearTimeout(timeout);
+                    this.socket.off('fw:ack', handler);
+                    resolve(data);
+                }
+            };
+            const timeout = setTimeout(() => {
+                this.socket.off('fw:ack', handler);
+                resolve({ requestId, success: false, error: 'Timeout' });
+            }, this.ackTimeout);
+            this.socket.on('fw:ack', handler);
+            this.socket.emit('integration:command', { requestId, action, params });
+        });
+    }
+    /**
+     * Sends a batch of commands to the editor as a single request and waits for acknowledgement.
+     * Returns an error response if not connected or if the ack times out.
+     * @param commands - Array of commands, each with an action name and optional params.
+     * @returns The editor's acknowledgement response for the entire batch.
+     */
+    async sendBatch(commands) {
+        if (!this.socket) {
+            return { requestId: '', success: false, error: 'Not connected' };
+        }
+        const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        return new Promise((resolve) => {
+            const handler = (data) => {
+                if (data.requestId === requestId) {
+                    clearTimeout(timeout);
+                    this.socket.off('fw:ack', handler);
+                    resolve(data);
+                }
+            };
+            const timeout = setTimeout(() => {
+                this.socket.off('fw:ack', handler);
+                resolve({ requestId, success: false, error: 'Timeout' });
+            }, this.ackTimeout);
+            this.socket.on('fw:ack', handler);
+            this.socket.emit('integration:batch', { requestId, commands });
+        });
+    }
+    /** Disconnects from the editor and releases the socket. */
+    disconnect() {
+        this.socket?.disconnect();
+        this.socket = null;
+    }
+}
+//# sourceMappingURL=editor-connection.js.map

package/dist/mcp/event-buffer.d.ts

@@ -0,0 +1,62 @@
+import type { BufferedEvent, EventFilterConfig } from './types.js';
+/**
+ * In-memory circular buffer for editor events with filtering, deduplication, and optional
+ * file-based persistence. Events are filtered by include/exclude patterns and deduplicated
+ * within a configurable time window.
+ */
+export declare class EventBuffer {
+    private events;
+    private maxSize;
+    private eventsFilePath;
+    private filter;
+    private lastEventByType;
+    /**
+     * @param maxSize - Maximum buffer capacity. Defaults to the filter's `maxBufferSize`.
+     * @param eventsFilePath - Path to a file for appending events as NDJSON. Pass `null` to disable.
+     *   Falls back to the `FW_EVENTS_FILE` environment variable if not specified.
+     * @param filter - Partial filter config merged with {@link DEFAULT_EVENT_FILTER}.
+     */
+    constructor(maxSize?: number, eventsFilePath?: string | null, filter?: Partial<EventFilterConfig>);
+    /**
+     * Updates the event filter configuration. If `maxBufferSize` changes, trims the buffer to fit.
+     * @param partial - Partial filter fields to merge into the current config.
+     * @returns The full updated filter configuration.
+     */
+    setFilter(partial: Partial<EventFilterConfig>): EventFilterConfig;
+    /** Returns a copy of the current event filter configuration. */
+    getFilter(): EventFilterConfig;
+    /**
+     * Pushes an event into the buffer. The event is dropped if it does not pass the
+     * include/exclude filters. If deduplication is enabled and an identical event type
+     * was pushed within the dedup window, the previous entry is replaced instead.
+     * Evicts the oldest events when the buffer exceeds `maxSize`.
+     * @param event - The event name.
+     * @param data - The event payload.
+     */
+    push(event: string, data: unknown): void;
+    private matchesFilter;
+    private appendToFile;
+    /**
+     * Returns all buffered events and clears the buffer.
+     * @returns A copy of all events that were in the buffer.
+     */
+    drain(): BufferedEvent[];
+    /**
+     * Returns a copy of all buffered events without clearing the buffer.
+     * @returns A copy of the current events.
+     */
+    peek(): BufferedEvent[];
+    /** Clears all events from the buffer. */
+    clear(): void;
+    /** The number of events currently in the buffer. */
+    get length(): number;
+}
+/**
+ * Tests whether an event name matches a filter pattern.
+ * Supports exact matching and prefix matching when the pattern ends with `*`.
+ * @param event - The event name to test.
+ * @param pattern - The pattern to match against. Trailing `*` enables prefix matching.
+ * @returns `true` if the event matches the pattern.
+ */
+export declare function matchPattern(event: string, pattern: string): boolean;
+//# sourceMappingURL=event-buffer.d.ts.map

package/dist/mcp/event-buffer.js

@@ -0,0 +1,150 @@
+import * as fs from 'fs';
+import { DEFAULT_EVENT_FILTER } from './types.js';
+/**
+ * In-memory circular buffer for editor events with filtering, deduplication, and optional
+ * file-based persistence. Events are filtered by include/exclude patterns and deduplicated
+ * within a configurable time window.
+ */
+export class EventBuffer {
+    events = [];
+    maxSize;
+    eventsFilePath;
+    filter;
+    lastEventByType = new Map();
+    /**
+     * @param maxSize - Maximum buffer capacity. Defaults to the filter's `maxBufferSize`.
+     * @param eventsFilePath - Path to a file for appending events as NDJSON. Pass `null` to disable.
+     *   Falls back to the `FW_EVENTS_FILE` environment variable if not specified.
+     * @param filter - Partial filter config merged with {@link DEFAULT_EVENT_FILTER}.
+     */
+    constructor(maxSize, eventsFilePath, filter) {
+        this.filter = { ...DEFAULT_EVENT_FILTER, ...filter };
+        this.maxSize = maxSize ?? this.filter.maxBufferSize;
+        // null = explicitly disabled, undefined = check env
+        this.eventsFilePath =
+            eventsFilePath === null ? null : (eventsFilePath ?? process.env.FW_EVENTS_FILE ?? null);
+    }
+    /**
+     * Updates the event filter configuration. If `maxBufferSize` changes, trims the buffer to fit.
+     * @param partial - Partial filter fields to merge into the current config.
+     * @returns The full updated filter configuration.
+     */
+    setFilter(partial) {
+        this.filter = { ...this.filter, ...partial };
+        if (partial.maxBufferSize !== undefined) {
+            this.maxSize = partial.maxBufferSize;
+            if (this.events.length > this.maxSize) {
+                this.events = this.events.slice(this.events.length - this.maxSize);
+            }
+        }
+        return { ...this.filter };
+    }
+    /** Returns a copy of the current event filter configuration. */
+    getFilter() {
+        return { ...this.filter };
+    }
+    /**
+     * Pushes an event into the buffer. The event is dropped if it does not pass the
+     * include/exclude filters. If deduplication is enabled and an identical event type
+     * was pushed within the dedup window, the previous entry is replaced instead.
+     * Evicts the oldest events when the buffer exceeds `maxSize`.
+     * @param event - The event name.
+     * @param data - The event payload.
+     */
+    push(event, data) {
+        if (!this.matchesFilter(event))
+            return;
+        const entry = {
+            event,
+            data,
+            timestamp: new Date().toISOString(),
+        };
+        // Dedup: if same event type within window, replace the last instance
+        if (this.filter.dedupeWindowMs > 0) {
+            const now = Date.now();
+            const lastTime = this.lastEventByType.get(event);
+            if (lastTime !== undefined && now - lastTime < this.filter.dedupeWindowMs) {
+                // Replace the last event of this type in the buffer
+                for (let i = this.events.length - 1; i >= 0; i--) {
+                    if (this.events[i].event === event) {
+                        this.events[i] = entry;
+                        this.lastEventByType.set(event, now);
+                        this.appendToFile(entry);
+                        return;
+                    }
+                }
+            }
+            this.lastEventByType.set(event, now);
+        }
+        this.events.push(entry);
+        // Evict oldest if over limit
+        if (this.events.length > this.maxSize) {
+            this.events = this.events.slice(this.events.length - this.maxSize);
+        }
+        this.appendToFile(entry);
+    }
+    matchesFilter(event) {
+        const { include, exclude } = this.filter;
+        // If include list is non-empty, event must match at least one pattern
+        if (include.length > 0) {
+            if (!include.some((pattern) => matchPattern(event, pattern))) {
+                return false;
+            }
+        }
+        // If event matches any exclude pattern, reject it
+        if (exclude.length > 0) {
+            if (exclude.some((pattern) => matchPattern(event, pattern))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    appendToFile(entry) {
+        if (!this.eventsFilePath)
+            return;
+        try {
+            fs.appendFileSync(this.eventsFilePath, JSON.stringify(entry) + '\n');
+        }
+        catch {
+            // File may have been atomically moved by the hook — next push creates a new one
+        }
+    }
+    /**
+     * Returns all buffered events and clears the buffer.
+     * @returns A copy of all events that were in the buffer.
+     */
+    drain() {
+        const result = [...this.events];
+        this.events = [];
+        return result;
+    }
+    /**
+     * Returns a copy of all buffered events without clearing the buffer.
+     * @returns A copy of the current events.
+     */
+    peek() {
+        return [...this.events];
+    }
+    /** Clears all events from the buffer. */
+    clear() {
+        this.events = [];
+    }
+    /** The number of events currently in the buffer. */
+    get length() {
+        return this.events.length;
+    }
+}
+/**
+ * Tests whether an event name matches a filter pattern.
+ * Supports exact matching and prefix matching when the pattern ends with `*`.
+ * @param event - The event name to test.
+ * @param pattern - The pattern to match against. Trailing `*` enables prefix matching.
+ * @returns `true` if the event matches the pattern.
+ */
+export function matchPattern(event, pattern) {
+    if (pattern.endsWith('*')) {
+        return event.startsWith(pattern.slice(0, -1));
+    }
+    return event === pattern;
+}
+//# sourceMappingURL=event-buffer.js.map

package/dist/mcp/index.d.ts

@@ -0,0 +1,12 @@
+export type { McpServerOptions, RegistrationDeps, AckResponse, BufferedEvent, EditorConnectionOptions, } from './types.js';
+export { EventBuffer } from './event-buffer.js';
+export { EditorConnection } from './editor-connection.js';
+export { offerClaudeRegistration } from './auto-registration.js';
+export { makeToolResult, makeErrorResult } from './response-utils.js';
+export { registerEditorTools } from './tools-editor.js';
+export { registerQueryTools } from './tools-query.js';
+export { registerTemplateTools } from './tools-template.js';
+export { registerPatternTools } from './tools-pattern.js';
+export { registerResources } from './resources.js';
+export { startMcpServer, mcpServerCommand } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.js

@@ -0,0 +1,11 @@
+export { EventBuffer } from './event-buffer.js';
+export { EditorConnection } from './editor-connection.js';
+export { offerClaudeRegistration } from './auto-registration.js';
+export { makeToolResult, makeErrorResult } from './response-utils.js';
+export { registerEditorTools } from './tools-editor.js';
+export { registerQueryTools } from './tools-query.js';
+export { registerTemplateTools } from './tools-template.js';
+export { registerPatternTools } from './tools-pattern.js';
+export { registerResources } from './resources.js';
+export { startMcpServer, mcpServerCommand } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/resources.d.ts

@@ -0,0 +1,14 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { EditorConnection } from './editor-connection.js';
+import type { EventBuffer } from './event-buffer.js';
+/**
+ * Registers MCP resources that expose editor state and event data.
+ * Registers two resources:
+ * - `fw://events` - read-only peek at the event buffer.
+ * - `fw://state` - current editor/workflow state fetched via the editor connection.
+ * @param mcp - The MCP server instance to register resources on.
+ * @param connection - The editor WebSocket connection used to query state.
+ * @param buffer - The event buffer to read events from.
+ */
+export declare function registerResources(mcp: McpServer, connection: EditorConnection, buffer: EventBuffer): void;
+//# sourceMappingURL=resources.d.ts.map

package/dist/mcp/resources.js

@@ -0,0 +1,55 @@
+/**
+ * Registers MCP resources that expose editor state and event data.
+ * Registers two resources:
+ * - `fw://events` - read-only peek at the event buffer.
+ * - `fw://state` - current editor/workflow state fetched via the editor connection.
+ * @param mcp - The MCP server instance to register resources on.
+ * @param connection - The editor WebSocket connection used to query state.
+ * @param buffer - The event buffer to read events from.
+ */
+export function registerResources(mcp, connection, buffer) {
+    mcp.resource('events', 'fw://events', { description: 'Read-only view of the event buffer (does not clear it)' }, async () => ({
+        contents: [
+            {
+                uri: 'fw://events',
+                text: JSON.stringify(buffer.peek(), null, 2),
+            },
+        ],
+    }));
+    mcp.resource('state', 'fw://state', { description: 'Current editor/workflow state' }, async () => {
+        if (!connection.isConnected) {
+            return {
+                contents: [
+                    {
+                        uri: 'fw://state',
+                        text: JSON.stringify({ error: 'Not connected to editor' }),
+                    },
+                ],
+            };
+        }
+        try {
+            const result = await connection.sendCommand('get-state', {});
+            return {
+                contents: [
+                    {
+                        uri: 'fw://state',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                contents: [
+                    {
+                        uri: 'fw://state',
+                        text: JSON.stringify({
+                            error: `Failed to get state: ${err instanceof Error ? err.message : String(err)}`,
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+}
+//# sourceMappingURL=resources.js.map

package/dist/mcp/response-utils.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Wraps a data payload into a successful MCP tool result with JSON text content.
+ * @param data - The result data to include in the response.
+ * @returns An MCP tool result object with `success: true` and the serialized data.
+ */
+export declare function makeToolResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * Wraps an error code and message into a failed MCP tool result.
+ * @param code - A machine-readable error code (e.g. "UNKNOWN_NODE_TYPE").
+ * @param message - A human-readable error description.
+ * @returns An MCP tool result object with `success: false`, `isError: true`, and the serialized error.
+ */
+export declare function makeErrorResult(code: string, message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/**
+ * Maps validation error codes to suggested next MCP tool actions.
+ * Used to guide LLM agents toward resolving workflow issues.
+ */
+export declare const ERROR_HINTS: Record<string, string>;
+/**
+ * Enriches validation items with actionable hints from {@link ERROR_HINTS} and optional
+ * friendly error explanations. Replaces `<nodeId>` placeholders in hints with actual node IDs.
+ * @param items - Array of validation errors/warnings, each with a message, severity, and optional code.
+ * @param friendlyErrorFn - Optional function that produces user-friendly error explanations.
+ * @returns A new array with `hint` and `friendly` fields added where applicable.
+ */
+export declare function addHintsToItems(items: Array<{
+    message: string;
+    severity: string;
+    nodeId?: string;
+    code?: string;
+}>, friendlyErrorFn?: (err: {
+    code: string;
+    message: string;
+    node?: string;
+}) => {
+    title: string;
+    explanation: string;
+    fix: string;
+    code: string;
+} | null): Array<{
+    message: string;
+    severity: string;
+    nodeId?: string;
+    code?: string;
+    hint?: string;
+    friendly?: {
+        title: string;
+        explanation: string;
+        fix: string;
+    };
+}>;
+//# sourceMappingURL=response-utils.d.ts.map