@windagency/valora 2.0.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../../src/utils/file-lock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAexD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,cAAc,CAIpB;IAEF;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAuE/F;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1F;;OAEG;IACG,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;IAuB7G;;OAEG;IACG,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BpH;;OAEG;IACG,cAAc,CAAC,CAAC,GAAG,OAAO,EAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,EACjC,OAAO,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,CAAC,CAAC;IAyCb;;OAEG;IACG,aAAa,CAAC,CAAC,GAAG,OAAO,EAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAgB,EAC1B,OAAO,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC;IAqBhB;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBlD;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAkB7D;;OAEG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsC7D;;OAEG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB7D;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGb;AAeD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAGpD"}

package/dist/utils/file-lock.js

@@ -0,0 +1,355 @@
+/**
+ * File Lock Utility - Atomic file operations with locking
+ *
+ * Provides thread-safe file operations for shared volumes across containers
+ */
+import { promises as fs } from 'fs';
+import { getLogger } from '../output/logger.js';
+import * as path from 'path';
+const logger = getLogger();
+/**
+ * Type guard to check if error has a code property (NodeJS error)
+ */
+function hasErrorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error;
+}
+export class FileLockManager {
+    defaultOptions = {
+        retries: 3,
+        retry_delay_ms: 100,
+        timeout_ms: 5000
+    };
+    /**
+     * Acquire a lock on a file
+     */
+    async acquireLock(filePath, lockerId, options) {
+        const opts = { ...this.defaultOptions, ...options };
+        const lockPath = this.getLockPath(filePath);
+        const expiresAt = new Date(Date.now() + opts.timeout_ms).toISOString();
+        const lock = {
+            acquired_at: new Date().toISOString(),
+            acquired_by: lockerId,
+            expires_at: expiresAt,
+            lock_id: this.generateLockId()
+        };
+        let attempt = 0;
+        let delay = opts.retry_delay_ms;
+        while (attempt <= opts.retries) {
+            try {
+                // Try to create lock file exclusively (fails if exists)
+                await fs.writeFile(lockPath, JSON.stringify(lock, null, 2), { flag: 'wx' });
+                logger.debug(`Lock acquired: ${lockPath} by ${lockerId}`);
+                return lock;
+            }
+            catch (error) {
+                if (hasErrorCode(error) && error.code === 'EEXIST') {
+                    // Lock file exists, check if it's expired
+                    try {
+                        const existingLockData = await fs.readFile(lockPath, 'utf-8');
+                        const existingLock = JSON.parse(existingLockData);
+                        // Check if lock is expired
+                        if (new Date(existingLock.expires_at) < new Date()) {
+                            logger.debug(`Lock expired, removing: ${lockPath}`);
+                            await this.releaseLock(filePath, existingLock.lock_id, true);
+                            // Retry immediately
+                            continue;
+                        }
+                        // Lock is still valid, wait and retry
+                        if (attempt < opts.retries) {
+                            logger.debug(`Lock held by ${existingLock.acquired_by}, retrying in ${delay}ms (attempt ${attempt + 1}/${opts.retries})`);
+                            await this.sleep(delay);
+                            delay *= 2; // Exponential backoff
+                            attempt++;
+                            continue;
+                        }
+                    }
+                    catch {
+                        // If we can't read the lock file, try to remove it
+                        try {
+                            await fs.unlink(lockPath);
+                            continue;
+                        }
+                        catch {
+                            // Ignore
+                        }
+                    }
+                }
+                // Final attempt failed
+                if (attempt >= opts.retries) {
+                    throw new Error(`Failed to acquire lock on ${filePath} after ${opts.retries} retries: ${getErrorMessage(error)}`);
+                }
+                attempt++;
+            }
+        }
+        throw new Error(`Failed to acquire lock on ${filePath}: maximum retries exceeded`);
+    }
+    /**
+     * Release a lock
+     */
+    async releaseLock(filePath, lockId, force = false) {
+        const lockPath = this.getLockPath(filePath);
+        try {
+            if (!force) {
+                // Verify lock belongs to the caller
+                const lockData = await fs.readFile(lockPath, 'utf-8');
+                const lock = JSON.parse(lockData);
+                if (lock.lock_id !== lockId) {
+                    throw new Error(`Cannot release lock: lock ID mismatch (expected ${lockId}, got ${lock.lock_id})`);
+                }
+            }
+            // Remove lock file
+            await fs.unlink(lockPath);
+            logger.debug(`Lock released: ${lockPath}`);
+        }
+        catch (error) {
+            if (!hasErrorCode(error) || error.code !== 'ENOENT') {
+                throw new Error(`Failed to release lock on ${filePath}: ${getErrorMessage(error)}`);
+            }
+            // Lock file doesn't exist, which is fine
+        }
+    }
+    /**
+     * Read a file with locking
+     */
+    async readWithLock(filePath, lockerId, options) {
+        let lock = null;
+        try {
+            // Acquire lock
+            lock = await this.acquireLock(filePath, lockerId, options);
+            // Read file
+            const data = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch (error) {
+            if (hasErrorCode(error) && error.code === 'ENOENT') {
+                return null; // File doesn't exist
+            }
+            throw new Error(`Failed to read file ${filePath}: ${getErrorMessage(error)}`);
+        }
+        finally {
+            // Always release lock
+            if (lock) {
+                await this.releaseLock(filePath, lock.lock_id);
+            }
+        }
+    }
+    /**
+     * Write a file with locking (atomic write)
+     */
+    async writeWithLock(filePath, data, lockerId, options) {
+        let lock = null;
+        try {
+            // Acquire lock
+            lock = await this.acquireLock(filePath, lockerId, options);
+            // Write to temporary file first (atomic operation)
+            const tempPath = `${filePath}.tmp.${lock.lock_id}`;
+            const jsonData = options?.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+            await fs.writeFile(tempPath, jsonData, 'utf-8');
+            // Atomic rename (this is the key operation)
+            await fs.rename(tempPath, filePath);
+            logger.debug(`File written atomically: ${filePath}`);
+        }
+        catch (error) {
+            throw new Error(`Failed to write file ${filePath}: ${getErrorMessage(error)}`);
+        }
+        finally {
+            // Always release lock
+            if (lock) {
+                await this.releaseLock(filePath, lock.lock_id);
+            }
+        }
+    }
+    /**
+     * Update a file with locking (read-modify-write)
+     */
+    async updateWithLock(filePath, lockerId, updater, options) {
+        let lock = null;
+        try {
+            // Acquire lock
+            lock = await this.acquireLock(filePath, lockerId, options);
+            // Read current data
+            let currentData = null;
+            try {
+                const fileContent = await fs.readFile(filePath, 'utf-8');
+                currentData = JSON.parse(fileContent);
+            }
+            catch (error) {
+                if (!hasErrorCode(error) || error.code !== 'ENOENT') {
+                    throw error;
+                }
+                // File doesn't exist, currentData stays null
+            }
+            // Apply update
+            const updatedData = updater(currentData);
+            // Write updated data atomically
+            const tempPath = `${filePath}.tmp.${lock.lock_id}`;
+            const jsonData = options?.pretty ? JSON.stringify(updatedData, null, 2) : JSON.stringify(updatedData);
+            await fs.writeFile(tempPath, jsonData, 'utf-8');
+            await fs.rename(tempPath, filePath);
+            logger.debug(`File updated atomically: ${filePath}`);
+            return updatedData;
+        }
+        catch (error) {
+            throw new Error(`Failed to update file ${filePath}: ${getErrorMessage(error)}`);
+        }
+        finally {
+            // Always release lock
+            if (lock) {
+                await this.releaseLock(filePath, lock.lock_id);
+            }
+        }
+    }
+    /**
+     * Append to an array in a JSON file with locking
+     */
+    async appendToArray(filePath, item, lockerId, arrayKey = 'items', options) {
+        await this.updateWithLock(filePath, lockerId, (current) => {
+            const data = current ?? {};
+            const currentArray = data[arrayKey];
+            if (!Array.isArray(currentArray)) {
+                data[arrayKey] = [item];
+            }
+            else {
+                const typedArray = currentArray;
+                data[arrayKey] = [...typedArray, item];
+            }
+            return data;
+        }, options);
+    }
+    /**
+     * Check if a file is locked
+     */
+    async isLocked(filePath) {
+        const lockPath = this.getLockPath(filePath);
+        try {
+            const lockData = await fs.readFile(lockPath, 'utf-8');
+            const lock = JSON.parse(lockData);
+            // Check if lock is expired
+            if (new Date(lock.expires_at) < new Date()) {
+                return false;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get lock information
+     */
+    async getLockInfo(filePath) {
+        const lockPath = this.getLockPath(filePath);
+        try {
+            const lockData = await fs.readFile(lockPath, 'utf-8');
+            const lock = JSON.parse(lockData);
+            // Check if lock is expired
+            if (new Date(lock.expires_at) < new Date()) {
+                return null;
+            }
+            return lock;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Clean up expired locks
+     */
+    async cleanupExpiredLocks(directory) {
+        let cleaned = 0;
+        try {
+            const files = await fs.readdir(directory);
+            for (const file of files) {
+                if (file.endsWith('.lock')) {
+                    const lockPath = path.join(directory, file);
+                    try {
+                        const lockData = await fs.readFile(lockPath, 'utf-8');
+                        const lock = JSON.parse(lockData);
+                        // Check if lock is expired
+                        if (new Date(lock.expires_at) < new Date()) {
+                            await fs.unlink(lockPath);
+                            logger.debug(`Cleaned up expired lock: ${lockPath}`);
+                            cleaned++;
+                        }
+                    }
+                    catch {
+                        // If we can't read/parse the lock, remove it
+                        try {
+                            await fs.unlink(lockPath);
+                            cleaned++;
+                        }
+                        catch {
+                            // Ignore
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            logger.error(`Failed to cleanup expired locks in ${directory}: ${getErrorMessage(error)}`);
+        }
+        return cleaned;
+    }
+    /**
+     * Force remove all locks in a directory
+     */
+    async forceRemoveAllLocks(directory) {
+        let removed = 0;
+        try {
+            const files = await fs.readdir(directory);
+            for (const file of files) {
+                if (file.endsWith('.lock')) {
+                    const lockPath = path.join(directory, file);
+                    try {
+                        await fs.unlink(lockPath);
+                        removed++;
+                    }
+                    catch {
+                        // Ignore
+                    }
+                }
+            }
+        }
+        catch (error) {
+            logger.error(`Failed to remove locks in ${directory}: ${getErrorMessage(error)}`);
+        }
+        return removed;
+    }
+    /**
+     * Get lock file path
+     */
+    getLockPath(filePath) {
+        return `${filePath}.lock`;
+    }
+    /**
+     * Generate unique lock ID
+     */
+    generateLockId() {
+        return `lock-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+    /**
+     * Sleep helper
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return String(error);
+}
+// Singleton instance for convenience
+let globalLockManager = null;
+/**
+ * Get global file lock manager instance
+ */
+export function getFileLockManager() {
+    globalLockManager ??= new FileLockManager();
+    return globalLockManager;
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/utils/file-lock.js.map

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

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

@@ -0,0 +1,71 @@
+/**
+ * File system utilities
+ */
+import type { Stats } from 'fs';
+export declare class DirectoryNotFoundError extends Error {
+    readonly dirPath: string;
+    constructor(dirPath: string);
+}
+export declare class FileNotFoundError extends Error {
+    readonly filePath: string;
+    constructor(filePath: string);
+}
+/**
+ * Read file with error handling
+ */
+export declare function readFile(filePath: string): Promise<string>;
+/**
+ * Write file with directory creation and sandbox resilience
+ */
+export declare function writeFile(filePath: string, content: string): Promise<void>;
+/**
+ * Append content to file with directory creation and sandbox resilience
+ */
+export declare function appendFile(filePath: string, content: string): Promise<void>;
+/**
+ * Check if file exists
+ */
+export declare function fileExists(filePath: string): boolean;
+/**
+ * Check if directory exists
+ */
+export declare function dirExists(dirPath: string): boolean;
+/**
+ * List files in directory
+ */
+export declare function listFiles(dirPath: string, extension?: string): Promise<string[]>;
+/**
+ * List directories
+ */
+export declare function listDirectories(dirPath: string): Promise<string[]>;
+/**
+ * Recursively find files by pattern
+ */
+export declare function findFiles(dirPath: string, pattern: RegExp, maxDepth?: number): Promise<string[]>;
+/**
+ * Ensure directory exists
+ */
+export declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Get file stats
+ */
+export declare function getFileStats(filePath: string): Promise<Stats>;
+/**
+ * @deprecated Use paths.ts and resource-resolver.ts instead.
+ * Resolve path relative to package root directory.
+ */
+export declare function resolveAIPath(...segments: string[]): string;
+/**
+ * @deprecated Use getPackageRoot() from './paths.js' instead.
+ * Returns the package root directory.
+ */
+export declare function getAIRoot(): string;
+/**
+ * Read and parse JSON file with type safety
+ */
+export declare function readJSON<T extends Record<string, unknown> = Record<string, unknown>>(filePath: string): Promise<T>;
+/**
+ * Write object as JSON to file
+ */
+export declare function writeJSON<T extends Record<string, unknown> = Record<string, unknown>>(filePath: string, data: T): Promise<void>;
+//# sourceMappingURL=file-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAUhC,qBAAa,sBAAuB,SAAQ,KAAK;aACpB,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAI3C;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aACf,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAI5C;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAShE;AAqBD;;GAEG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhF;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBtF;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUxE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyB1G;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CASnE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAyBlC;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzF,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1F,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,GACL,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/utils/file-utils.js

@@ -0,0 +1,235 @@
+/**
+ * File system utilities
+ */
+import * as fsSync from 'fs';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { shouldGracefullyHandleFileErrors } from './environment.js';
+export class DirectoryNotFoundError extends Error {
+    dirPath;
+    constructor(dirPath) {
+        super(`Directory not found: ${dirPath}`);
+        this.dirPath = dirPath;
+        this.name = 'DirectoryNotFoundError';
+    }
+}
+export class FileNotFoundError extends Error {
+    filePath;
+    constructor(filePath) {
+        super(`File not found: ${filePath}`);
+        this.filePath = filePath;
+        this.name = 'FileNotFoundError';
+    }
+}
+/**
+ * Read file with error handling
+ */
+export async function readFile(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new FileNotFoundError(filePath);
+        }
+        throw error;
+    }
+}
+/**
+ * Safely handle file system errors in sandboxed environments
+ */
+function handleFileSystemError(error, operation, filePath) {
+    const isPermissionError = error.code === 'EPERM' || error.code === 'EACCES';
+    const shouldGracefullyHandle = shouldGracefullyHandleFileErrors();
+    if (isPermissionError && shouldGracefullyHandle) {
+        // Silently ignore permission errors in production sandboxed environments
+        // This allows the application to continue functioning
+        console.debug(`File operation skipped in sandboxed environment: ${operation} ${filePath}`);
+        return;
+    }
+    // Re-throw other errors, or permission errors in test environments (for proper testing)
+    throw error;
+}
+/**
+ * Write file with directory creation and sandbox resilience
+ */
+export async function writeFile(filePath, content) {
+    try {
+        const dir = path.dirname(filePath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(filePath, content, 'utf-8');
+    }
+    catch (error) {
+        handleFileSystemError(error, 'write', filePath);
+    }
+}
+/**
+ * Append content to file with directory creation and sandbox resilience
+ */
+export async function appendFile(filePath, content) {
+    try {
+        const dir = path.dirname(filePath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.appendFile(filePath, content, 'utf-8');
+    }
+    catch (error) {
+        handleFileSystemError(error, 'append', filePath);
+    }
+}
+/**
+ * Check if file exists
+ */
+export function fileExists(filePath) {
+    return fsSync.existsSync(filePath);
+}
+/**
+ * Check if directory exists
+ */
+export function dirExists(dirPath) {
+    return fsSync.existsSync(dirPath);
+}
+/**
+ * List files in directory
+ */
+export async function listFiles(dirPath, extension) {
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        let files = entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+        if (extension) {
+            files = files.filter((file) => file.endsWith(extension));
+        }
+        return files;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new DirectoryNotFoundError(dirPath);
+        }
+        throw error;
+    }
+}
+/**
+ * List directories
+ */
+export async function listDirectories(dirPath) {
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new DirectoryNotFoundError(dirPath);
+        }
+        throw error;
+    }
+}
+/**
+ * Recursively find files by pattern
+ */
+export async function findFiles(dirPath, pattern, maxDepth = 10) {
+    const results = [];
+    async function search(currentPath, depth) {
+        if (depth > maxDepth)
+            return;
+        const entries = await fs.readdir(currentPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(currentPath, entry.name);
+            if (entry.isDirectory()) {
+                await search(fullPath, depth + 1);
+            }
+            else if (entry.isFile() && pattern.test(entry.name)) {
+                results.push(fullPath);
+            }
+        }
+    }
+    if (!dirExists(dirPath)) {
+        throw new DirectoryNotFoundError(dirPath);
+    }
+    await search(dirPath, 0);
+    return results;
+}
+/**
+ * Ensure directory exists
+ */
+export async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+/**
+ * Get file stats
+ */
+export async function getFileStats(filePath) {
+    try {
+        return await fs.stat(filePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new FileNotFoundError(filePath);
+        }
+        throw error;
+    }
+}
+/**
+ * @deprecated Use paths.ts and resource-resolver.ts instead.
+ * Resolve path relative to package root directory.
+ */
+export function resolveAIPath(...segments) {
+    return path.join(getAIRoot(), ...segments);
+}
+/**
+ * @deprecated Use getPackageRoot() from './paths.js' instead.
+ * Returns the package root directory.
+ */
+export function getAIRoot() {
+    const currentFilename = fileURLToPath(import.meta.url);
+    let dir = dirname(currentFilename);
+    // Walk up to find the package root (directory with package.json "valora" AND data/)
+    for (let i = 0; i < 10; i++) {
+        const pkgPath = path.join(dir, 'package.json');
+        const dataDir = path.join(dir, 'data');
+        if (fileExists(pkgPath) && fileExists(dataDir)) {
+            try {
+                const pkg = JSON.parse(fsSync.readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name === 'valora') {
+                    return dir;
+                }
+            }
+            catch {
+                // Invalid JSON, keep searching
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback
+    return path.resolve(dirname(currentFilename), '..', '..');
+}
+/**
+ * Read and parse JSON file with type safety
+ */
+export async function readJSON(filePath) {
+    try {
+        const content = await readFile(filePath);
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new FileNotFoundError(filePath);
+        }
+        // Re-throw JSON parsing errors with more context
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON in file ${filePath}: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Write object as JSON to file
+ */
+export async function writeJSON(filePath, data) {
+    const content = JSON.stringify(data, null, 2);
+    await writeFile(filePath, content);
+}
+//# sourceMappingURL=file-utils.js.map