@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/utils/StdioMessageReader.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Stdio Message Reader
+ *
+ * Reads Content-Length framed messages from a stream (LSP-style).
+ * Handles partial messages across multiple chunks and ignores non-framed output.
+ *
+ * Message format:
+ * ```
+ * Content-Length: 67\r\n
+ * \r\n
+ * {"jsonrpc":"2.0","id":1,"method":"invoke","params":{...}}
+ * ```
+ *
+ * @module utils/StdioMessageReader
+ */
+import { EventEmitter } from 'events';
+/**
+ * Message reader for Content-Length framed messages
+ *
+ * Implements the LSP (Language Server Protocol) message framing format.
+ * This allows reliable JSON-RPC communication over stdio even when the
+ * ability writes logs or debug output to stdout.
+ *
+ * @example
+ * ```typescript
+ * const reader = new StdioMessageReader();
+ *
+ * reader.on('message', (message) => {
+ *   console.log('Received:', message);
+ * });
+ *
+ * reader.on('error', (error) => {
+ *   console.error('Parse error:', error);
+ * });
+ *
+ * // Feed data chunks
+ * process.stdout.on('data', (chunk) => {
+ *   reader.onData(chunk);
+ * });
+ * ```
+ */
+export declare class StdioMessageReader extends EventEmitter {
+    /**
+     * Buffer for accumulating incoming data
+     */
+    private buffer;
+    /**
+     * Whether the reader has been destroyed
+     */
+    private destroyed;
+    /**
+     * Header end marker
+     */
+    private static readonly HEADER_END;
+    /**
+     * Content-Length header regex
+     * Note: No multiline flag - header must be clean (no garbage before it)
+     */
+    private static readonly CONTENT_LENGTH_PATTERN;
+    /**
+     * Process incoming data chunk
+     *
+     * Appends chunk to buffer and attempts to parse complete messages.
+     * May emit multiple 'message' events if buffer contains multiple messages.
+     *
+     * @param chunk - Incoming data chunk
+     *
+     * @example
+     * ```typescript
+     * stream.on('data', (chunk) => {
+     *   reader.onData(chunk);
+     * });
+     * ```
+     */
+    onData(chunk: Buffer): void;
+    /**
+     * Attempt to read and emit complete messages from buffer
+     *
+     * Continues reading until no complete message can be extracted.
+     * Handles multiple messages in a single buffer.
+     */
+    private tryReadMessages;
+    /**
+     * Attempt to read a single complete message
+     *
+     * @returns Parsed message object, or null if no complete message available
+     * @throws {Error} If header is malformed or JSON is invalid
+     */
+    private tryReadSingleMessage;
+    /**
+     * Skip to next potential header in buffer
+     *
+     * Used for error recovery when a malformed message is encountered.
+     * Searches for the next "Content-Length:" pattern.
+     */
+    private skipToNextHeader;
+    /**
+     * Get current buffer size (for debugging/monitoring)
+     *
+     * @returns Number of bytes in buffer
+     */
+    getBufferSize(): number;
+    /**
+     * Clear the internal buffer
+     *
+     * Useful for resetting state after errors or for cleanup.
+     */
+    clearBuffer(): void;
+    /**
+     * Destroy the reader
+     *
+     * Cleans up resources and prevents further processing.
+     */
+    destroy(): void;
+    /**
+     * Check if reader is destroyed
+     *
+     * @returns true if destroyed
+     */
+    isDestroyed(): boolean;
+}
+//# sourceMappingURL=StdioMessageReader.d.ts.map

package/dist/utils/StdioMessageReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StdioMessageReader.d.ts","sourceRoot":"","sources":["../../src/utils/StdioMessageReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAmB;IAEjC;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAc;IAEhD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAmC;IAEjF;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY3B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAqBvB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAmD5B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;OAIG;IACH,WAAW,IAAI,IAAI;IAInB;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAMf;;;;OAIG;IACH,WAAW,IAAI,OAAO;CAGvB"}

package/dist/utils/StdioMessageReader.js

@@ -0,0 +1,209 @@
+/**
+ * Stdio Message Reader
+ *
+ * Reads Content-Length framed messages from a stream (LSP-style).
+ * Handles partial messages across multiple chunks and ignores non-framed output.
+ *
+ * Message format:
+ * ```
+ * Content-Length: 67\r\n
+ * \r\n
+ * {"jsonrpc":"2.0","id":1,"method":"invoke","params":{...}}
+ * ```
+ *
+ * @module utils/StdioMessageReader
+ */
+import { EventEmitter } from 'events';
+/**
+ * Message reader for Content-Length framed messages
+ *
+ * Implements the LSP (Language Server Protocol) message framing format.
+ * This allows reliable JSON-RPC communication over stdio even when the
+ * ability writes logs or debug output to stdout.
+ *
+ * @example
+ * ```typescript
+ * const reader = new StdioMessageReader();
+ *
+ * reader.on('message', (message) => {
+ *   console.log('Received:', message);
+ * });
+ *
+ * reader.on('error', (error) => {
+ *   console.error('Parse error:', error);
+ * });
+ *
+ * // Feed data chunks
+ * process.stdout.on('data', (chunk) => {
+ *   reader.onData(chunk);
+ * });
+ * ```
+ */
+export class StdioMessageReader extends EventEmitter {
+    /**
+     * Buffer for accumulating incoming data
+     */
+    buffer = Buffer.alloc(0);
+    /**
+     * Whether the reader has been destroyed
+     */
+    destroyed = false;
+    /**
+     * Header end marker
+     */
+    static HEADER_END = '\r\n\r\n';
+    /**
+     * Content-Length header regex
+     * Note: No multiline flag - header must be clean (no garbage before it)
+     */
+    static CONTENT_LENGTH_PATTERN = /^Content-Length:\s*(\d+)\s*$/i;
+    /**
+     * Process incoming data chunk
+     *
+     * Appends chunk to buffer and attempts to parse complete messages.
+     * May emit multiple 'message' events if buffer contains multiple messages.
+     *
+     * @param chunk - Incoming data chunk
+     *
+     * @example
+     * ```typescript
+     * stream.on('data', (chunk) => {
+     *   reader.onData(chunk);
+     * });
+     * ```
+     */
+    onData(chunk) {
+        if (this.destroyed) {
+            return;
+        }
+        // Append to buffer
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        // Try to extract messages
+        this.tryReadMessages();
+    }
+    /**
+     * Attempt to read and emit complete messages from buffer
+     *
+     * Continues reading until no complete message can be extracted.
+     * Handles multiple messages in a single buffer.
+     */
+    tryReadMessages() {
+        while (true) {
+            try {
+                const message = this.tryReadSingleMessage();
+                if (!message) {
+                    // No complete message available
+                    break;
+                }
+                // Emit the message
+                this.emit('message', message);
+            }
+            catch (error) {
+                // Emit error but continue processing
+                this.emit('error', error);
+                // Try to recover by skipping to next potential header
+                this.skipToNextHeader();
+            }
+        }
+    }
+    /**
+     * Attempt to read a single complete message
+     *
+     * @returns Parsed message object, or null if no complete message available
+     * @throws {Error} If header is malformed or JSON is invalid
+     */
+    tryReadSingleMessage() {
+        // Look for header end marker
+        const headerEndIndex = this.buffer.indexOf(StdioMessageReader.HEADER_END);
+        if (headerEndIndex === -1) {
+            // No complete header yet
+            return null;
+        }
+        // Extract header
+        const headerBytes = this.buffer.slice(0, headerEndIndex);
+        const header = headerBytes.toString('utf8');
+        // Parse Content-Length
+        const match = header.match(StdioMessageReader.CONTENT_LENGTH_PATTERN);
+        if (!match || !match[1]) {
+            throw new Error(`Invalid message header: missing or malformed Content-Length\nHeader: ${header}`);
+        }
+        const contentLength = parseInt(match[1], 10);
+        if (isNaN(contentLength) || contentLength < 0) {
+            throw new Error(`Invalid Content-Length value: ${match[1]}`);
+        }
+        // Check if we have the complete message
+        const messageStart = headerEndIndex + StdioMessageReader.HEADER_END.length;
+        const messageEnd = messageStart + contentLength;
+        if (this.buffer.length < messageEnd) {
+            // Need more data - message is incomplete
+            return null;
+        }
+        // Extract message bytes
+        const messageBytes = this.buffer.slice(messageStart, messageEnd);
+        const messageJson = messageBytes.toString('utf8');
+        // Parse JSON
+        let message;
+        try {
+            message = JSON.parse(messageJson);
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON in message body: ${error instanceof Error ? error.message : String(error)}\nJSON: ${messageJson.substring(0, 200)}`);
+        }
+        // Remove processed data from buffer
+        this.buffer = this.buffer.slice(messageEnd);
+        return message;
+    }
+    /**
+     * Skip to next potential header in buffer
+     *
+     * Used for error recovery when a malformed message is encountered.
+     * Searches for the next "Content-Length:" pattern.
+     */
+    skipToNextHeader() {
+        const searchString = this.buffer.toString('utf8');
+        const nextHeaderIndex = searchString.indexOf('Content-Length:', 1);
+        if (nextHeaderIndex === -1) {
+            // No next header found - clear buffer
+            this.buffer = Buffer.alloc(0);
+        }
+        else {
+            // Skip to next header
+            this.buffer = this.buffer.slice(nextHeaderIndex);
+        }
+    }
+    /**
+     * Get current buffer size (for debugging/monitoring)
+     *
+     * @returns Number of bytes in buffer
+     */
+    getBufferSize() {
+        return this.buffer.length;
+    }
+    /**
+     * Clear the internal buffer
+     *
+     * Useful for resetting state after errors or for cleanup.
+     */
+    clearBuffer() {
+        this.buffer = Buffer.alloc(0);
+    }
+    /**
+     * Destroy the reader
+     *
+     * Cleans up resources and prevents further processing.
+     */
+    destroy() {
+        this.destroyed = true;
+        this.buffer = Buffer.alloc(0);
+        this.removeAllListeners();
+    }
+    /**
+     * Check if reader is destroyed
+     *
+     * @returns true if destroyed
+     */
+    isDestroyed() {
+        return this.destroyed;
+    }
+}
+//# sourceMappingURL=StdioMessageReader.js.map

package/dist/utils/StdioMessageReader.js.map

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

package/dist/utils/StdioMessageWriter.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Stdio Message Writer
+ *
+ * Writes Content-Length framed messages to a stream (LSP-style).
+ * Ensures reliable message delivery even when other output is written to the stream.
+ *
+ * Message format:
+ * ```
+ * Content-Length: 67\r\n
+ * \r\n
+ * {"jsonrpc":"2.0","id":1,"result":{"value":42}}
+ * ```
+ *
+ * @module utils/StdioMessageWriter
+ */
+import type { Writable } from 'stream';
+/**
+ * Message writer for Content-Length framed messages
+ *
+ * Implements the LSP (Language Server Protocol) message framing format.
+ * Automatically calculates content length and formats headers.
+ *
+ * @example
+ * ```typescript
+ * const writer = new StdioMessageWriter(process.stdout);
+ *
+ * // Write a JSON-RPC message
+ * await writer.write({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   result: { value: 42 }
+ * });
+ * ```
+ */
+export declare class StdioMessageWriter {
+    /**
+     * Output stream
+     */
+    private readonly stream;
+    /**
+     * Whether the writer has been destroyed
+     */
+    private destroyed;
+    /**
+     * Header separator
+     */
+    private static readonly HEADER_SEPARATOR;
+    /**
+     * Create a new message writer
+     *
+     * @param stream - Output stream (typically stdout)
+     */
+    constructor(stream: Writable);
+    /**
+     * Write a framed message to the stream
+     *
+     * Serializes the message to JSON, calculates byte length, formats
+     * Content-Length header, and writes everything to the stream.
+     *
+     * @param message - Message object to write (will be JSON-stringified)
+     * @returns Promise that resolves when message is fully written
+     *
+     * @throws {Error} If writer is destroyed or write fails
+     *
+     * @example
+     * ```typescript
+     * await writer.write({
+     *   jsonrpc: '2.0',
+     *   id: 1,
+     *   method: 'invoke',
+     *   params: { toolName: 'add', toolInput: { a: 5, b: 3 } }
+     * });
+     * ```
+     */
+    write(message: Record<string, unknown>): Promise<void>;
+    /**
+     * Flush the stream
+     *
+     * Ensures all buffered data is written to the underlying stream.
+     *
+     * @returns Promise that resolves when flush is complete
+     */
+    flush(): Promise<void>;
+    /**
+     * Destroy the writer
+     *
+     * Cleans up resources. After calling destroy(), the writer cannot be used.
+     * Note: This does NOT close the underlying stream.
+     */
+    destroy(): void;
+    /**
+     * Check if writer is destroyed
+     *
+     * @returns true if destroyed
+     */
+    isDestroyed(): boolean;
+    /**
+     * Get the underlying stream
+     *
+     * @returns The writable stream
+     */
+    getStream(): Writable;
+}
+//# sourceMappingURL=StdioMessageWriter.d.ts.map

package/dist/utils/StdioMessageWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StdioMessageWriter.d.ts","sourceRoot":"","sources":["../../src/utils/StdioMessageWriter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAkB;IAC7B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAElC;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAElD;;;;OAIG;gBACS,MAAM,EAAE,QAAQ;IAI5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC5D;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAIf;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAItB;;;;OAIG;IACH,SAAS,IAAI,QAAQ;CAGtB"}

package/dist/utils/StdioMessageWriter.js

@@ -0,0 +1,162 @@
+/**
+ * Stdio Message Writer
+ *
+ * Writes Content-Length framed messages to a stream (LSP-style).
+ * Ensures reliable message delivery even when other output is written to the stream.
+ *
+ * Message format:
+ * ```
+ * Content-Length: 67\r\n
+ * \r\n
+ * {"jsonrpc":"2.0","id":1,"result":{"value":42}}
+ * ```
+ *
+ * @module utils/StdioMessageWriter
+ */
+/**
+ * Message writer for Content-Length framed messages
+ *
+ * Implements the LSP (Language Server Protocol) message framing format.
+ * Automatically calculates content length and formats headers.
+ *
+ * @example
+ * ```typescript
+ * const writer = new StdioMessageWriter(process.stdout);
+ *
+ * // Write a JSON-RPC message
+ * await writer.write({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   result: { value: 42 }
+ * });
+ * ```
+ */
+export class StdioMessageWriter {
+    /**
+     * Output stream
+     */
+    stream;
+    /**
+     * Whether the writer has been destroyed
+     */
+    destroyed = false;
+    /**
+     * Header separator
+     */
+    static HEADER_SEPARATOR = '\r\n';
+    /**
+     * Create a new message writer
+     *
+     * @param stream - Output stream (typically stdout)
+     */
+    constructor(stream) {
+        this.stream = stream;
+    }
+    /**
+     * Write a framed message to the stream
+     *
+     * Serializes the message to JSON, calculates byte length, formats
+     * Content-Length header, and writes everything to the stream.
+     *
+     * @param message - Message object to write (will be JSON-stringified)
+     * @returns Promise that resolves when message is fully written
+     *
+     * @throws {Error} If writer is destroyed or write fails
+     *
+     * @example
+     * ```typescript
+     * await writer.write({
+     *   jsonrpc: '2.0',
+     *   id: 1,
+     *   method: 'invoke',
+     *   params: { toolName: 'add', toolInput: { a: 5, b: 3 } }
+     * });
+     * ```
+     */
+    async write(message) {
+        if (this.destroyed) {
+            throw new Error('Cannot write: StdioMessageWriter has been destroyed');
+        }
+        // Serialize message to JSON
+        const messageJson = JSON.stringify(message);
+        // Calculate UTF-8 byte length (not character length!)
+        const messageBytes = Buffer.from(messageJson, 'utf8');
+        const contentLength = messageBytes.length;
+        // Format header
+        const header = `Content-Length: ${contentLength}${StdioMessageWriter.HEADER_SEPARATOR}${StdioMessageWriter.HEADER_SEPARATOR}`;
+        // Write header + message
+        const fullMessage = header + messageJson;
+        // Write to stream and handle backpressure
+        return new Promise((resolve, reject) => {
+            const writeSucceeded = this.stream.write(fullMessage, 'utf8', (error) => {
+                if (error) {
+                    reject(new Error(`Failed to write message: ${error.message}`));
+                }
+                else {
+                    resolve();
+                }
+            });
+            // If write returned false, wait for drain event
+            if (!writeSucceeded) {
+                this.stream.once('drain', () => {
+                    resolve();
+                });
+            }
+        });
+    }
+    /**
+     * Flush the stream
+     *
+     * Ensures all buffered data is written to the underlying stream.
+     *
+     * @returns Promise that resolves when flush is complete
+     */
+    async flush() {
+        if (this.destroyed) {
+            return;
+        }
+        return new Promise((resolve) => {
+            // Check if stream has end() method (for proper cleanup)
+            if (typeof this.stream.end === 'function') {
+                // Don't actually end the stream, just make sure it's flushed
+                // We'll use cork/uncork if available
+                if (typeof this.stream.uncork === 'function') {
+                    this.stream.uncork();
+                }
+            }
+            // Wait for drain if needed
+            if (this.stream.writableNeedDrain) {
+                this.stream.once('drain', () => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    /**
+     * Destroy the writer
+     *
+     * Cleans up resources. After calling destroy(), the writer cannot be used.
+     * Note: This does NOT close the underlying stream.
+     */
+    destroy() {
+        this.destroyed = true;
+    }
+    /**
+     * Check if writer is destroyed
+     *
+     * @returns true if destroyed
+     */
+    isDestroyed() {
+        return this.destroyed;
+    }
+    /**
+     * Get the underlying stream
+     *
+     * @returns The writable stream
+     */
+    getStream() {
+        return this.stream;
+    }
+}
+//# sourceMappingURL=StdioMessageWriter.js.map

package/dist/utils/StdioMessageWriter.js.map

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