@geanatz/cortex-mcp 5.0.1

package/dist/utils/cache.d.ts

@@ -0,0 +1,104 @@
+/**
+ * In-memory cache with TTL support
+ * Provides efficient caching for storage operations
+ */
+/**
+ * Cache configuration options
+ */
+export interface CacheOptions {
+    /** Default TTL in milliseconds (default: 5 minutes) */
+    defaultTtl?: number;
+    /** Maximum number of entries (default: 1000) */
+    maxSize?: number;
+    /** Enable statistics tracking (default: true) */
+    trackStats?: boolean;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    size: number;
+    evictions: number;
+    hitRate: number;
+}
+/**
+ * Generic in-memory cache with TTL and LRU eviction
+ */
+export declare class Cache<T> {
+    private readonly cache;
+    private readonly defaultTtl;
+    private readonly maxSize;
+    private readonly trackStats;
+    private stats;
+    constructor(options?: CacheOptions);
+    /**
+     * Get a value from cache
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set a value in cache
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a key from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Delete all keys matching a prefix
+     */
+    deletePrefix(prefix: string): number;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Get or set with async factory
+     */
+    getOrSet(key: string, factory: () => Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * Invalidate entries matching a pattern
+     */
+    invalidate(pattern: RegExp): number;
+    /**
+     * Prune expired entries
+     */
+    prune(): number;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+}
+/**
+ * Create cache keys for different entity types
+ */
+export declare const CacheKeys: {
+    readonly task: (id: string) => string;
+    readonly taskList: (parentId?: string) => string;
+    readonly allTasks: () => string;
+    readonly taskFolders: () => string;
+    readonly artifact: (taskId: string, phase: string) => string;
+    readonly allArtifacts: (taskId: string) => string;
+    readonly hierarchy: (parentId?: string) => string;
+};
+/**
+ * Cache invalidation patterns
+ */
+export declare const InvalidationPatterns: {
+    readonly task: (id: string) => RegExp;
+    readonly allTasks: () => RegExp;
+    readonly artifact: (taskId: string) => RegExp;
+};

package/dist/utils/cache.js

@@ -0,0 +1,196 @@
+/**
+ * In-memory cache with TTL support
+ * Provides efficient caching for storage operations
+ */
+/**
+ * Generic in-memory cache with TTL and LRU eviction
+ */
+export class Cache {
+    cache = new Map();
+    defaultTtl;
+    maxSize;
+    trackStats;
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+    };
+    constructor(options = {}) {
+        this.defaultTtl = options.defaultTtl ?? 5 * 60 * 1000; // 5 minutes
+        this.maxSize = options.maxSize ?? 1000;
+        this.trackStats = options.trackStats ?? true;
+    }
+    /**
+     * Get a value from cache
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            if (this.trackStats)
+                this.stats.misses++;
+            return undefined;
+        }
+        // Check expiration
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            if (this.trackStats)
+                this.stats.misses++;
+            return undefined;
+        }
+        // Update access metadata
+        entry.accessCount++;
+        entry.lastAccessedAt = Date.now();
+        if (this.trackStats)
+            this.stats.hits++;
+        return entry.value;
+    }
+    /**
+     * Set a value in cache
+     */
+    set(key, value, ttl) {
+        // Evict if at capacity
+        if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+            this.evictLRU();
+        }
+        const now = Date.now();
+        this.cache.set(key, {
+            value,
+            createdAt: now,
+            expiresAt: now + (ttl ?? this.defaultTtl),
+            accessCount: 0,
+            lastAccessedAt: now,
+        });
+    }
+    /**
+     * Check if 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 key from cache
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Delete all keys matching a prefix
+     */
+    deletePrefix(prefix) {
+        let count = 0;
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Clear all entries
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        return {
+            ...this.stats,
+            size: this.cache.size,
+            hitRate: total > 0 ? this.stats.hits / total : 0,
+        };
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.stats = { hits: 0, misses: 0, evictions: 0 };
+    }
+    /**
+     * Get or set with async factory
+     */
+    async getOrSet(key, factory, ttl) {
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = await factory();
+        this.set(key, value, ttl);
+        return value;
+    }
+    /**
+     * Invalidate entries matching a pattern
+     */
+    invalidate(pattern) {
+        let count = 0;
+        for (const key of this.cache.keys()) {
+            if (pattern.test(key)) {
+                this.cache.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Prune expired entries
+     */
+    prune() {
+        const now = Date.now();
+        let count = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Evict least recently used entry
+     */
+    evictLRU() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.lastAccessedAt < oldestTime) {
+                oldestTime = entry.lastAccessedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            if (this.trackStats)
+                this.stats.evictions++;
+        }
+    }
+}
+/**
+ * Create cache keys for different entity types
+ */
+export const CacheKeys = {
+    task: (id) => `task:${id}`,
+    taskList: (parentId) => `tasks:${parentId ?? 'root'}`,
+    allTasks: () => 'tasks:all',
+    taskFolders: () => 'task-folders',
+    artifact: (taskId, phase) => `artifact:${taskId}:${phase}`,
+    allArtifacts: (taskId) => `artifacts:${taskId}`,
+    hierarchy: (parentId) => `hierarchy:${parentId ?? 'root'}`,
+};
+/**
+ * Cache invalidation patterns
+ */
+export const InvalidationPatterns = {
+    task: (id) => new RegExp(`^(task:${id}|tasks:|hierarchy:)`),
+    allTasks: () => /^(task:|tasks:|hierarchy:|task-folders)/,
+    artifact: (taskId) => new RegExp(`^artifact(s)?:${taskId}`),
+};

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

@@ -0,0 +1,101 @@
+/**
+ * Check if a file or directory exists
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Check if path is readable
+ */
+export declare function isReadable(filePath: string): Promise<boolean>;
+/**
+ * Check if path is writable
+ */
+export declare function isWritable(filePath: string): Promise<boolean>;
+/**
+ * Check if path is a directory
+ */
+export declare function isDirectory(filePath: string): Promise<boolean>;
+/**
+ * Check if path is a file
+ */
+export declare function isFile(filePath: string): Promise<boolean>;
+/**
+ * Ensure directory exists, creating it if necessary
+ */
+export declare function ensureDirectory(dirPath: string): Promise<void>;
+/**
+ * Atomic file write using temporary file
+ * Ensures data integrity by writing to temp file first, then renaming
+ */
+export declare function atomicWriteFile(filePath: string, content: string): Promise<void>;
+/**
+ * Read file with error handling
+ */
+export declare function readFile(filePath: string): Promise<string>;
+/**
+ * Read file or return null if not found
+ */
+export declare function readFileOrNull(filePath: string): Promise<string | null>;
+/**
+ * Read and parse JSON file
+ */
+export declare function readJsonFile<T>(filePath: string): Promise<T>;
+/**
+ * Read JSON file or return null if not found
+ */
+export declare function readJsonFileOrNull<T>(filePath: string): Promise<T | null>;
+/**
+ * Write JSON file with pretty printing
+ */
+export declare function writeJsonFile<T>(filePath: string, data: T, indent?: number): Promise<void>;
+/**
+ * Delete file if it exists
+ */
+export declare function deleteFile(filePath: string): Promise<boolean>;
+/**
+ * Delete directory recursively
+ */
+export declare function deleteDirectory(dirPath: string): Promise<boolean>;
+/**
+ * List directory contents with filtering options
+ */
+export interface ListDirectoryOptions {
+    /** Only return directories */
+    directoriesOnly?: boolean;
+    /** Only return files */
+    filesOnly?: boolean;
+    /** Filter by pattern (regex or string) */
+    pattern?: RegExp | string;
+    /** Sort results */
+    sort?: boolean;
+}
+export declare function listDirectory(dirPath: string, options?: ListDirectoryOptions): Promise<string[]>;
+/**
+ * Copy file
+ */
+export declare function copyFile(source: string, destination: string): Promise<void>;
+/**
+ * Move file (rename)
+ */
+export declare function moveFile(source: string, destination: string): Promise<void>;
+/**
+ * Get file stats or null if not found
+ */
+export declare function getFileStats(filePath: string): Promise<{
+    size: number;
+    created: Date;
+    modified: Date;
+    isDirectory: boolean;
+    isFile: boolean;
+} | null>;
+/**
+ * Resolve path relative to base
+ */
+export declare function resolvePath(base: string, ...paths: string[]): string;
+/**
+ * Get relative path
+ */
+export declare function getRelativePath(from: string, to: string): string;
+/**
+ * Join paths
+ */
+export declare function joinPath(...paths: string[]): string;

package/dist/utils/file-utils.js

@@ -0,0 +1,270 @@
+import { promises as fs, constants } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
+import { StorageError } from '../errors/errors.js';
+/**
+ * Check if a file or directory exists
+ */
+export async function fileExists(filePath) {
+    try {
+        await fs.access(filePath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if path is readable
+ */
+export async function isReadable(filePath) {
+    try {
+        await fs.access(filePath, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if path is writable
+ */
+export async function isWritable(filePath) {
+    try {
+        await fs.access(filePath, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if path is a directory
+ */
+export async function isDirectory(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if path is a file
+ */
+export async function isFile(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure directory exists, creating it if necessary
+ */
+export async function ensureDirectory(dirPath) {
+    try {
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+    catch (error) {
+        // Ignore if directory already exists
+        if (error.code !== 'EEXIST') {
+            throw StorageError.directoryError(dirPath, error);
+        }
+    }
+}
+/**
+ * Atomic file write using temporary file
+ * Ensures data integrity by writing to temp file first, then renaming
+ */
+export async function atomicWriteFile(filePath, content) {
+    const tempFile = `${filePath}.${Date.now()}.tmp`;
+    try {
+        // Ensure parent directory exists
+        await ensureDirectory(dirname(filePath));
+        // Write to temp file
+        await fs.writeFile(tempFile, content, 'utf-8');
+        // Atomic rename
+        await fs.rename(tempFile, filePath);
+    }
+    catch (error) {
+        // Clean up temp file on error
+        try {
+            await fs.unlink(tempFile);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw StorageError.writeError(filePath, error);
+    }
+}
+/**
+ * Read file with error handling
+ */
+export async function readFile(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        throw StorageError.readError(filePath, error);
+    }
+}
+/**
+ * Read file or return null if not found
+ */
+export async function readFileOrNull(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw StorageError.readError(filePath, error);
+    }
+}
+/**
+ * Read and parse JSON file
+ */
+export async function readJsonFile(filePath) {
+    const content = await readFile(filePath);
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw StorageError.parseError(filePath, 'JSON', error);
+    }
+}
+/**
+ * Read JSON file or return null if not found
+ */
+export async function readJsonFileOrNull(filePath) {
+    const content = await readFileOrNull(filePath);
+    if (content === null) {
+        return null;
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw StorageError.parseError(filePath, 'JSON', error);
+    }
+}
+/**
+ * Write JSON file with pretty printing
+ */
+export async function writeJsonFile(filePath, data, indent = 2) {
+    const content = JSON.stringify(data, null, indent);
+    await atomicWriteFile(filePath, content);
+}
+/**
+ * Delete file if it exists
+ */
+export async function deleteFile(filePath) {
+    try {
+        await fs.unlink(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Delete directory recursively
+ */
+export async function deleteDirectory(dirPath) {
+    try {
+        await fs.rm(dirPath, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function listDirectory(dirPath, options = {}) {
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        let results = entries.filter(entry => {
+            if (options.directoriesOnly && !entry.isDirectory())
+                return false;
+            if (options.filesOnly && !entry.isFile())
+                return false;
+            if (options.pattern) {
+                const pattern = typeof options.pattern === 'string'
+                    ? new RegExp(options.pattern)
+                    : options.pattern;
+                if (!pattern.test(entry.name))
+                    return false;
+            }
+            return true;
+        }).map(entry => entry.name);
+        if (options.sort !== false) {
+            results.sort();
+        }
+        return results;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw StorageError.directoryError(dirPath, error);
+    }
+}
+/**
+ * Copy file
+ */
+export async function copyFile(source, destination) {
+    await ensureDirectory(dirname(destination));
+    await fs.copyFile(source, destination);
+}
+/**
+ * Move file (rename)
+ */
+export async function moveFile(source, destination) {
+    await ensureDirectory(dirname(destination));
+    await fs.rename(source, destination);
+}
+/**
+ * Get file stats or null if not found
+ */
+export async function getFileStats(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return {
+            size: stats.size,
+            created: stats.birthtime,
+            modified: stats.mtime,
+            isDirectory: stats.isDirectory(),
+            isFile: stats.isFile(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve path relative to base
+ */
+export function resolvePath(base, ...paths) {
+    return resolve(base, ...paths);
+}
+/**
+ * Get relative path
+ */
+export function getRelativePath(from, to) {
+    return relative(from, to);
+}
+/**
+ * Join paths
+ */
+export function joinPath(...paths) {
+    return join(...paths);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Central utility exports
+ * Import utilities from this module for convenience
+ */
+export * from './file-utils.js';
+export * from './string-utils.js';
+export * from './storage-config.js';
+export * from './validation.js';
+export * from './response-builder.js';
+export * from './cache.js';
+export * from './logger.js';
+export * from './version.js';

package/dist/utils/index.js

@@ -0,0 +1,12 @@
+/**
+ * Central utility exports
+ * Import utilities from this module for convenience
+ */
+export * from './file-utils.js';
+export * from './string-utils.js';
+export * from './storage-config.js';
+export * from './validation.js';
+export * from './response-builder.js';
+export * from './cache.js';
+export * from './logger.js';
+export * from './version.js';