kemdicode-mcp 1.15.0

package/dist/utils/cache.d.ts

@@ -0,0 +1,124 @@
+/**
+ * KemdiCode MCP Server
+ * Copyright (C) 2025-2026 Kemdi Sp. z o.o.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Cache options for creating a new cache instance
+ */
+export interface CacheOptions {
+    /** Maximum number of entries (default: 1000) */
+    maxEntries?: number;
+    /** Default TTL in milliseconds (default: 5 minutes) */
+    defaultTTL?: number;
+}
+/**
+ * LRU Cache with TTL support
+ *
+ * Uses a Map for O(1) access with LRU eviction based on insertion order.
+ * Entries expire after TTL and are lazily cleaned up.
+ *
+ * @example
+ * const cache = new LRUCache<string>({ maxEntries: 100, defaultTTL: 60000 });
+ * cache.set('key', 'value');
+ * const value = cache.get('key');
+ */
+export declare class LRUCache<T> {
+    private cache;
+    private readonly maxEntries;
+    private readonly defaultTTL;
+    constructor(options?: CacheOptions);
+    /**
+     * Get a value from the cache
+     * Returns undefined if not found or expired
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set a value in the cache
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Optional TTL in milliseconds (overrides default)
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a specific key from the cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get the current number of entries (including potentially expired ones)
+     */
+    get size(): number;
+    /**
+     * Get or compute a value
+     * If the key exists and is valid, returns cached value.
+     * Otherwise, calls the factory function, caches the result, and returns it.
+     *
+     * @param key - Cache key
+     * @param factory - Function to compute the value if not cached
+     * @param ttl - Optional TTL in milliseconds
+     */
+    getOrSet(key: string, factory: () => T, ttl?: number): T;
+    /**
+     * Async version of getOrSet
+     * If the key exists and is valid, returns cached value.
+     * Otherwise, calls the async factory function, caches the result, and returns it.
+     *
+     * @param key - Cache key
+     * @param factory - Async function to compute the value if not cached
+     * @param ttl - Optional TTL in milliseconds
+     */
+    getOrSetAsync(key: string, factory: () => Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * Remove expired entries (cleanup)
+     * Called periodically or manually to free memory
+     */
+    prune(): number;
+    /**
+     * Get cache statistics
+     */
+    stats(): {
+        size: number;
+        maxEntries: number;
+        defaultTTL: number;
+    };
+}
+/**
+ * Global cache instances for common use cases
+ */
+/** Cache for git operations (root detection, repo checks) - uses config TTL */
+export declare const gitCache: LRUCache<string | boolean | null>;
+/** Cache for file system operations (file exists, file type) - uses config TTL */
+export declare const fsCache: LRUCache<string | boolean>;
+/** Cache for project detection results - uses config TTL */
+export declare const projectCache: LRUCache<unknown>;
+/**
+ * Clear all global caches
+ * Call when project context changes significantly
+ */
+export declare function clearAllCaches(): void;
+/**
+ * Prune all global caches
+ * Call periodically to free memory from expired entries
+ */
+export declare function pruneAllCaches(): number;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAsBH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,GAAE,YAAiB;IAOtC;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAoB/B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAsB9C;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAezB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC;IAWxD;;;;;;;;OAQG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAWrF;;;OAGG;IACH,KAAK,IAAI,MAAM;IAcf;;OAEG;IACH,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;CAOlE;AAUD;;GAEG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,QAAQ,mCAGnB,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,OAAO,4BAGlB,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,YAAY,mBAGvB,CAAC;AAEH;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAIrC;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/dist/utils/cache.js

@@ -0,0 +1,228 @@
+/**
+ * KemdiCode MCP Server
+ * Copyright (C) 2025-2026 Kemdi Sp. z o.o.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * LRU Cache with TTL Support
+ *
+ * Simple in-memory cache with Least Recently Used eviction and Time-To-Live expiration.
+ * Optimized for caching expensive operations like git commands and file system checks.
+ *
+ * @module utils/cache
+ */
+import { config } from '../config/index.js';
+/**
+ * LRU Cache with TTL support
+ *
+ * Uses a Map for O(1) access with LRU eviction based on insertion order.
+ * Entries expire after TTL and are lazily cleaned up.
+ *
+ * @example
+ * const cache = new LRUCache<string>({ maxEntries: 100, defaultTTL: 60000 });
+ * cache.set('key', 'value');
+ * const value = cache.get('key');
+ */
+export class LRUCache {
+    cache;
+    maxEntries;
+    defaultTTL;
+    constructor(options = {}) {
+        this.cache = new Map();
+        const cacheConfig = config.get('cache');
+        this.maxEntries = options.maxEntries ?? cacheConfig.maxEntries;
+        this.defaultTTL = options.defaultTTL ?? cacheConfig.defaultTtl;
+    }
+    /**
+     * Get a value from the cache
+     * Returns undefined if not found or expired
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Move to end (most recently used) by reinserting
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.value;
+    }
+    /**
+     * Set a value in the cache
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Optional TTL in milliseconds (overrides default)
+     */
+    set(key, value, ttl) {
+        // Remove if exists (for LRU ordering)
+        this.cache.delete(key);
+        // Evict oldest entries if at capacity
+        while (this.cache.size >= this.maxEntries) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+            }
+            else {
+                break;
+            }
+        }
+        const now = Date.now();
+        this.cache.set(key, {
+            value,
+            timestamp: now,
+            expiresAt: now + (ttl ?? this.defaultTTL),
+        });
+    }
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete a specific key from the cache
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the current number of entries (including potentially expired ones)
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get or compute a value
+     * If the key exists and is valid, returns cached value.
+     * Otherwise, calls the factory function, caches the result, and returns it.
+     *
+     * @param key - Cache key
+     * @param factory - Function to compute the value if not cached
+     * @param ttl - Optional TTL in milliseconds
+     */
+    getOrSet(key, factory, ttl) {
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = factory();
+        this.set(key, value, ttl);
+        return value;
+    }
+    /**
+     * Async version of getOrSet
+     * If the key exists and is valid, returns cached value.
+     * Otherwise, calls the async factory function, caches the result, and returns it.
+     *
+     * @param key - Cache key
+     * @param factory - Async function to compute the value if not cached
+     * @param ttl - Optional TTL in milliseconds
+     */
+    async getOrSetAsync(key, factory, ttl) {
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = await factory();
+        this.set(key, value, ttl);
+        return value;
+    }
+    /**
+     * Remove expired entries (cleanup)
+     * Called periodically or manually to free memory
+     */
+    prune() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.cache) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+    /**
+     * Get cache statistics
+     */
+    stats() {
+        return {
+            size: this.cache.size,
+            maxEntries: this.maxEntries,
+            defaultTTL: this.defaultTTL,
+        };
+    }
+}
+/**
+ * Get cache configuration values
+ * Called lazily to allow config to be set up first
+ */
+function getCacheConfig() {
+    return config.get('cache');
+}
+/**
+ * Global cache instances for common use cases
+ */
+/** Cache for git operations (root detection, repo checks) - uses config TTL */
+export const gitCache = new LRUCache({
+    maxEntries: getCacheConfig().gitSize,
+    defaultTTL: getCacheConfig().gitTtl,
+});
+/** Cache for file system operations (file exists, file type) - uses config TTL */
+export const fsCache = new LRUCache({
+    maxEntries: getCacheConfig().fsSize,
+    defaultTTL: getCacheConfig().fsTtl,
+});
+/** Cache for project detection results - uses config TTL */
+export const projectCache = new LRUCache({
+    maxEntries: getCacheConfig().projectSize,
+    defaultTTL: getCacheConfig().projectTtl,
+});
+/**
+ * Clear all global caches
+ * Call when project context changes significantly
+ */
+export function clearAllCaches() {
+    gitCache.clear();
+    fsCache.clear();
+    projectCache.clear();
+}
+/**
+ * Prune all global caches
+ * Call periodically to free memory from expired entries
+ */
+export function pruneAllCaches() {
+    return gitCache.prune() + fsCache.prune() + projectCache.prune();
+}
+//# sourceMappingURL=cache.js.map

package/dist/utils/cache.js.map

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

package/dist/utils/commandExecutor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * KemdiCode MCP Server
+ * Copyright (C) 2025-2026 Kemdi Sp. z o.o.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Options for command execution
+ */
+export interface ExecuteCommandOptions {
+    /** Callback for stdout streaming */
+    onProgress?: (output: string) => void;
+    /** Timeout in milliseconds (default: 300000) */
+    timeout?: number;
+    /** AbortSignal for cancellation support */
+    signal?: AbortSignal;
+    /** Working directory for the command */
+    cwd?: string;
+    /** Additional environment variables */
+    env?: Record<string, string>;
+}
+/**
+ * Execute a shell command with timeout and progress streaming
+ * @param {string} command - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {Function} [onProgress] - Callback for stdout streaming
+ * @param {number} [timeout=300000] - Timeout in milliseconds
+ * @returns {Promise<string>} Command stdout
+ * @throws {Error} On timeout, spawn failure, or non-zero exit code
+ */
+export declare function executeCommand(command: string, args: string[], onProgress?: (output: string) => void, timeout?: number): Promise<string>;
+/**
+ * Execute a shell command with full options including AbortController support
+ * @param {string} command - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {ExecuteCommandOptions} options - Execution options
+ * @returns {Promise<string>} Command stdout
+ * @throws {AbortError} On abort signal
+ * @throws {TimeoutError} On timeout
+ * @throws {CommandError} On spawn failure or non-zero exit code
+ */
+export declare function executeCommandWithOptions(command: string, args: string[], options?: ExecuteCommandOptions): Promise<string>;
+//# sourceMappingURL=commandExecutor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commandExecutor.d.ts","sourceRoot":"","sources":["../../src/utils/commandExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgBH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,EACrC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA0IjB"}

package/dist/utils/commandExecutor.js

@@ -0,0 +1,165 @@
+/**
+ * KemdiCode MCP Server
+ * Copyright (C) 2025-2026 Kemdi Sp. z o.o.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Command Executor Module
+ *
+ * Executes shell commands with timeout support, progress streaming,
+ * AbortController for cancellation, and automatic configuration injection.
+ *
+ * @module utils/commandExecutor
+ */
+import { spawn } from 'child_process';
+import { Logger } from './logger.js';
+import { TimeoutError, CommandError, AbortError } from './errors.js';
+import { config } from '../config/index.js';
+/**
+ * Execute a shell command with timeout and progress streaming
+ * @param {string} command - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {Function} [onProgress] - Callback for stdout streaming
+ * @param {number} [timeout=300000] - Timeout in milliseconds
+ * @returns {Promise<string>} Command stdout
+ * @throws {Error} On timeout, spawn failure, or non-zero exit code
+ */
+export async function executeCommand(command, args, onProgress, timeout) {
+    const effectiveTimeout = timeout ?? config.get('timeouts').command;
+    return executeCommandWithOptions(command, args, { onProgress, timeout: effectiveTimeout });
+}
+/**
+ * Execute a shell command with full options including AbortController support
+ * @param {string} command - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {ExecuteCommandOptions} options - Execution options
+ * @returns {Promise<string>} Command stdout
+ * @throws {AbortError} On abort signal
+ * @throws {TimeoutError} On timeout
+ * @throws {CommandError} On spawn failure or non-zero exit code
+ */
+export async function executeCommandWithOptions(command, args, options = {}) {
+    const timeouts = config.get('timeouts');
+    const { onProgress, timeout = timeouts.command, signal, cwd, env: extraEnv } = options;
+    return new Promise((resolve, reject) => {
+        // Check if already aborted
+        if (signal?.aborted) {
+            reject(new AbortError(`${command} ${args.join(' ')}`, { command, args }));
+            return;
+        }
+        const start = Date.now();
+        Logger.commandExecution(command, args, start);
+        const spawnOptions = {
+            env: { ...process.env, ...extraEnv },
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        };
+        if (cwd) {
+            spawnOptions.cwd = cwd;
+        }
+        const proc = spawn(command, args, spawnOptions);
+        let stdout = '', stderr = '', done = false, lastLen = 0;
+        const fullCommand = `${command} ${args.join(' ')}`;
+        // Cleanup function to properly terminate
+        const cleanup = (reason) => {
+            if (done)
+                return false;
+            done = true;
+            clearTimeout(timer);
+            if (abortHandler) {
+                signal?.removeEventListener('abort', abortHandler);
+            }
+            if (reason !== 'complete') {
+                try {
+                    proc.kill('SIGTERM');
+                    // Force kill after configured delay if still running
+                    setTimeout(() => {
+                        try {
+                            proc.kill('SIGKILL');
+                        }
+                        catch {
+                            // Process may have already exited
+                        }
+                    }, timeouts.forceKill);
+                }
+                catch {
+                    // Process may have already exited
+                }
+            }
+            return true;
+        };
+        // Handle abort signal
+        let abortHandler;
+        if (signal) {
+            abortHandler = () => {
+                if (cleanup('abort')) {
+                    if (stdout.trim()) {
+                        resolve(stdout.trim() + '\n\n[ABORTED]');
+                    }
+                    else {
+                        reject(new AbortError(fullCommand, { command, args }));
+                    }
+                }
+            };
+            signal.addEventListener('abort', abortHandler);
+        }
+        // Handle timeout
+        const timer = setTimeout(() => {
+            if (cleanup('timeout')) {
+                if (stdout.trim()) {
+                    // Return partial output with timeout notice
+                    resolve(stdout.trim() + `\n\n[TIMEOUT: ${timeout / 1000}s limit]`);
+                }
+                else {
+                    // No output captured, throw TimeoutError with context
+                    reject(new TimeoutError(fullCommand, timeout, undefined, { command, args }));
+                }
+            }
+        }, timeout);
+        proc.stdout?.on('data', (data) => {
+            stdout += data.toString();
+            if (onProgress && stdout.length > lastLen) {
+                onProgress(stdout.substring(lastLen));
+                lastLen = stdout.length;
+            }
+        });
+        proc.stderr?.on('data', (data) => {
+            stderr += data.toString();
+            if (stderr.includes('RESOURCE_EXHAUSTED')) {
+                Logger.error('Quota exceeded - try fallback model');
+            }
+        });
+        proc.on('error', (err) => {
+            if (cleanup('complete')) {
+                reject(new CommandError(fullCommand, `Spawn failed: ${err.message}`, undefined, undefined, {
+                    command,
+                    args,
+                }));
+            }
+        });
+        proc.on('close', (code) => {
+            if (cleanup('complete')) {
+                Logger.commandComplete(start, code, stdout.length);
+                if (code === 0) {
+                    resolve(stdout.trim());
+                }
+                else {
+                    reject(new CommandError(fullCommand, stderr.trim() || `Command exited with code ${code}`, code ?? undefined, stderr.trim() || undefined, { command, args }));
+                }
+            }
+        });
+    });
+}
+//# sourceMappingURL=commandExecutor.js.map

package/dist/utils/commandExecutor.js.map

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

package/dist/utils/edit-utils.d.ts

@@ -0,0 +1,72 @@
+/**
+ * KemdiCode MCP Server
+ * Copyright (C) 2025-2026 Kemdi Sp. z o.o.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Result of a line-based edit operation
+ */
+export interface EditResult {
+    success: boolean;
+    path: string;
+    backup?: string;
+    error?: string;
+    code?: string;
+}
+/**
+ * Read file and split into lines
+ * Preserves original line endings for accurate reconstruction
+ */
+export declare function readFileLines(path: string): Promise<string[]>;
+/**
+ * Write lines back to file, optionally creating a backup
+ *
+ * @param path - File path to write
+ * @param lines - Array of lines (without trailing newlines)
+ * @param createBackup - Whether to create .bak backup
+ * @returns Backup path if created, null otherwise
+ */
+export declare function writeFileLines(path: string, lines: string[], createBackup: boolean): Promise<string | null>;
+/**
+ * Validate line range for editing operations
+ *
+ * @param startLine - First line (1-based, inclusive)
+ * @param endLine - Last line (1-based, inclusive)
+ * @param totalLines - Total number of lines in file
+ * @throws Error if range is invalid
+ */
+export declare function validateLineRange(startLine: number, endLine: number, totalLines: number): void;
+/**
+ * Validate single line number for insertion
+ *
+ * @param line - Line number (1-based)
+ * @param totalLines - Total number of lines in file
+ * @param allowAppend - Allow line = totalLines + 1 for appending
+ * @throws Error if line is invalid
+ */
+export declare function validateLineNumber(line: number, totalLines: number, allowAppend?: boolean): void;
+/**
+ * Truncate string for preview purposes
+ *
+ * @param str - String to truncate
+ * @param maxLength - Maximum length (default 200)
+ * @returns Truncated string with ellipsis if needed
+ */
+export declare function truncateForPreview(str: string, maxLength?: number): string;
+/**
+ * Count the number of lines in a string
+ */
+export declare function countLines(str: string): number;
+//# sourceMappingURL=edit-utils.d.ts.map

package/dist/utils/edit-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-utils.d.ts","sourceRoot":"","sources":["../../src/utils/edit-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAInE;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EAAE,EACf,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAkB9F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,WAAW,GAAE,OAAc,GAC1B,IAAI,CAYN;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,MAAM,CAK/E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9C"}