@exaudeus/workrail 0.1.0 → 0.1.2

package/dist/infrastructure/storage/context-storage.d.ts

@@ -0,0 +1,150 @@
+import { CheckpointMetadata, SessionInfo, CompressedBlob, BlobMetadata } from '../../types/context-types';
+export interface IContextStorage {
+    saveCheckpoint(metadata: CheckpointMetadata, blob: CompressedBlob): Promise<void>;
+    loadCheckpoint(checkpointId: string): Promise<{
+        metadata: CheckpointMetadata;
+        blob: CompressedBlob;
+    }>;
+    listCheckpoints(sessionId: string, limit?: number, offset?: number): Promise<CheckpointMetadata[]>;
+    deleteCheckpoint(checkpointId: string): Promise<void>;
+    getSession(sessionId: string): Promise<SessionInfo | null>;
+    upsertSession(session: SessionInfo): Promise<void>;
+    deleteSession(sessionId: string): Promise<void>;
+    getStorageStats(): Promise<StorageStats>;
+    validateIntegrity(): Promise<ValidationResult>;
+    close(): Promise<void>;
+}
+export interface IMetadataStorage {
+    initialize(): Promise<void>;
+    saveCheckpointMetadata(metadata: CheckpointMetadata): Promise<void>;
+    getCheckpointMetadata(checkpointId: string): Promise<CheckpointMetadata | null>;
+    listCheckpointMetadata(sessionId: string, limit?: number, offset?: number): Promise<CheckpointMetadata[]>;
+    deleteCheckpointMetadata(checkpointId: string): Promise<void>;
+    upsertSessionInfo(session: SessionInfo): Promise<void>;
+    getSessionInfo(sessionId: string): Promise<SessionInfo | null>;
+    deleteSessionInfo(sessionId: string): Promise<void>;
+    getMetadataStats(): Promise<MetadataStats>;
+    acquireSessionLock(sessionId: string, operationType: string, timeoutMs?: number): Promise<string>;
+    releaseSessionLock(operationId: string): Promise<void>;
+    updateOperationHeartbeat(operationId: string): Promise<void>;
+    cleanupStaleOperations(): Promise<number>;
+    close(): Promise<void>;
+}
+export interface IBlobStorage {
+    initialize(): Promise<void>;
+    saveBlob(sessionId: string, checkpointId: string, blob: CompressedBlob): Promise<BlobMetadata>;
+    loadBlob(blobMetadata: BlobMetadata): Promise<CompressedBlob>;
+    deleteBlob(blobMetadata: BlobMetadata): Promise<void>;
+    getBlobStats(): Promise<BlobStats>;
+    validateBlobIntegrity(): Promise<BlobValidationResult>;
+    cleanupOrphanedBlobs(referencedPaths: string[]): Promise<number>;
+    getAvailableSpace(): Promise<number>;
+    close(): Promise<void>;
+}
+export interface StorageStats {
+    totalSessions: number;
+    totalCheckpoints: number;
+    totalSizeBytes: number;
+    averageCheckpointSize: number;
+    oldestCheckpoint?: string;
+    newestCheckpoint?: string;
+    storageUtilization: number;
+}
+export interface MetadataStats {
+    databaseSizeBytes: number;
+    totalSessions: number;
+    totalCheckpoints: number;
+    activeOperations: number;
+    averageCheckpointSize: number;
+    indexEfficiency: number;
+}
+export interface BlobStats {
+    totalFiles: number;
+    totalSizeBytes: number;
+    averageFileSize: number;
+    compressionRatio: number;
+    availableSpaceBytes: number;
+    directoryStructure: DirectoryInfo[];
+}
+export interface DirectoryInfo {
+    path: string;
+    fileCount: number;
+    totalSize: number;
+    lastModified?: string;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+    repairSuggestions: string[];
+}
+export interface BlobValidationResult {
+    isValid: boolean;
+    corruptedFiles: string[];
+    missingFiles: string[];
+    orphanedFiles: string[];
+    checksumMismatches: ChecksumMismatch[];
+}
+export interface ValidationError {
+    type: 'CORRUPTION' | 'MISSING_DATA' | 'CONSTRAINT_VIOLATION' | 'ORPHANED_DATA';
+    description: string;
+    affectedItems: string[];
+    severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+}
+export interface ValidationWarning {
+    type: 'PERFORMANCE' | 'CLEANUP_NEEDED' | 'QUOTA_WARNING';
+    description: string;
+    suggestion: string;
+}
+export interface ChecksumMismatch {
+    filePath: string;
+    expectedChecksum: string;
+    actualChecksum: string;
+    checkpointId: string;
+}
+export interface ContextStorageConfig {
+    dataDirectory: string;
+    database: {
+        path: string;
+        timeout: number;
+        maxConnections: number;
+        walMode: boolean;
+    };
+    blobs: {
+        directory: string;
+        filePermissions: number;
+        directoryPermissions: number;
+        atomicWrites: boolean;
+    };
+    concurrency: {
+        operationTimeoutMs: number;
+        maxRetries: number;
+        heartbeatIntervalMs: number;
+        cleanupIntervalMs: number;
+    };
+    quotas: {
+        maxTotalSize: number;
+        maxCheckpointsPerSession: number;
+        warningThreshold: number;
+        cleanupThreshold: number;
+    };
+    validation: {
+        enableChecksumValidation: boolean;
+        integrityCheckIntervalMs: number;
+        enableOrphanedFileCleanup: boolean;
+    };
+}
+export declare function createDefaultContextStorageConfig(baseDir?: string): ContextStorageConfig;
+export interface IContextStorageFactory {
+    createMetadataStorage(config: ContextStorageConfig): Promise<IMetadataStorage>;
+    createBlobStorage(config: ContextStorageConfig): Promise<IBlobStorage>;
+    createContextStorage(config: ContextStorageConfig): Promise<IContextStorage>;
+}
+export interface StorageOperationContext {
+    operationId: string;
+    operationType: string;
+    sessionId?: string;
+    checkpointId?: string;
+    startTime: number;
+    metadata?: Record<string, any>;
+}

package/dist/infrastructure/storage/context-storage.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultContextStorageConfig = createDefaultContextStorageConfig;
+function createDefaultContextStorageConfig(baseDir) {
+    const os = require('os');
+    const path = require('path');
+    const defaultBaseDir = baseDir || path.join(os.homedir(), '.workrail');
+    return {
+        dataDirectory: defaultBaseDir,
+        database: {
+            path: 'workrail.db',
+            timeout: 5000,
+            maxConnections: 10,
+            walMode: true
+        },
+        blobs: {
+            directory: 'contexts',
+            filePermissions: 0o600,
+            directoryPermissions: 0o700,
+            atomicWrites: true
+        },
+        concurrency: {
+            operationTimeoutMs: 5000,
+            maxRetries: 3,
+            heartbeatIntervalMs: 1000,
+            cleanupIntervalMs: 60000
+        },
+        quotas: {
+            maxTotalSize: 10 * 1024 * 1024 * 1024,
+            maxCheckpointsPerSession: 1000,
+            warningThreshold: 0.8,
+            cleanupThreshold: 0.9
+        },
+        validation: {
+            enableChecksumValidation: true,
+            integrityCheckIntervalMs: 24 * 60 * 60 * 1000,
+            enableOrphanedFileCleanup: true
+        }
+    };
+}

package/dist/infrastructure/storage/filesystem-blob-storage.d.ts

@@ -0,0 +1,27 @@
+import { IBlobStorage, ContextStorageConfig, BlobStats, BlobValidationResult } from './context-storage';
+import { CompressedBlob, BlobMetadata } from '../../types/context-types';
+export declare class FileSystemBlobStorage implements IBlobStorage {
+    private config;
+    private blobDirectory;
+    private isInitialized;
+    constructor(config: ContextStorageConfig);
+    initialize(): Promise<void>;
+    saveBlob(sessionId: string, checkpointId: string, blob: CompressedBlob): Promise<BlobMetadata>;
+    loadBlob(blobMetadata: BlobMetadata): Promise<CompressedBlob>;
+    deleteBlob(blobMetadata: BlobMetadata): Promise<void>;
+    getBlobStats(): Promise<BlobStats>;
+    validateBlobIntegrity(): Promise<BlobValidationResult>;
+    cleanupOrphanedBlobs(referencedPaths: string[]): Promise<number>;
+    getAvailableSpace(): Promise<number>;
+    close(): Promise<void>;
+    private ensureInitialized;
+    private ensureDirectory;
+    private generateBlobPath;
+    private atomicWrite;
+    private calculateChecksum;
+    private verifyFileIntegrity;
+    private fileExists;
+    private getAllBlobFiles;
+    private analyzeDirectory;
+    private cleanupEmptyDirectories;
+}

package/dist/infrastructure/storage/filesystem-blob-storage.js

@@ -0,0 +1,363 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSystemBlobStorage = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+class FileSystemBlobStorage {
+    constructor(config) {
+        this.isInitialized = false;
+        this.config = config;
+        this.blobDirectory = path_1.default.join(config.dataDirectory, config.blobs.directory);
+    }
+    async initialize() {
+        if (this.isInitialized) {
+            return;
+        }
+        try {
+            await this.ensureDirectory(this.blobDirectory);
+            const currentDate = new Date();
+            const yearMonth = `${currentDate.getFullYear()}/${String(currentDate.getMonth() + 1).padStart(2, '0')}`;
+            await this.ensureDirectory(path_1.default.join(this.blobDirectory, yearMonth));
+            this.isInitialized = true;
+            console.log('✅ Filesystem blob storage initialized');
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize filesystem blob storage: ${error}`);
+        }
+    }
+    async saveBlob(sessionId, checkpointId, blob) {
+        this.ensureInitialized();
+        try {
+            const blobPath = this.generateBlobPath(sessionId, checkpointId);
+            const fullPath = path_1.default.join(this.blobDirectory, blobPath);
+            await this.ensureDirectory(path_1.default.dirname(fullPath));
+            const checksum = this.calculateChecksum(blob.data);
+            await this.atomicWrite(fullPath, blob.data);
+            await this.verifyFileIntegrity(fullPath, checksum, blob.data.length);
+            const metadata = {
+                checkpointId,
+                sessionId,
+                path: blobPath,
+                sizeBytes: blob.data.length,
+                hash: checksum,
+                encrypted: false
+            };
+            console.log(`💾 Saved blob: ${blobPath} (${blob.data.length} bytes, ratio: ${blob.compressionRatio.toFixed(2)})`);
+            return metadata;
+        }
+        catch (error) {
+            throw new Error(`Failed to save blob: ${error}`);
+        }
+    }
+    async loadBlob(blobMetadata) {
+        this.ensureInitialized();
+        try {
+            const fullPath = path_1.default.join(this.blobDirectory, blobMetadata.path);
+            if (!await this.fileExists(fullPath)) {
+                throw new Error(`Blob file not found: ${blobMetadata.path}`);
+            }
+            const data = await fs_1.default.promises.readFile(fullPath);
+            if (this.config.validation.enableChecksumValidation) {
+                const actualChecksum = this.calculateChecksum(data);
+                if (actualChecksum !== blobMetadata.hash) {
+                    throw new Error(`Blob integrity check failed for ${blobMetadata.path}. ` +
+                        `Expected: ${blobMetadata.hash}, Got: ${actualChecksum}`);
+                }
+            }
+            if (data.length !== blobMetadata.sizeBytes) {
+                throw new Error(`Blob size mismatch for ${blobMetadata.path}. ` +
+                    `Expected: ${blobMetadata.sizeBytes} bytes, Got: ${data.length} bytes`);
+            }
+            console.log(`📖 Loaded blob: ${blobMetadata.path} (${data.length} bytes)`);
+            return {
+                data,
+                originalSize: blobMetadata.sizeBytes,
+                compressedSize: data.length,
+                compressionRatio: 1.0,
+                algorithm: 'gzip'
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to load blob: ${error}`);
+        }
+    }
+    async deleteBlob(blobMetadata) {
+        this.ensureInitialized();
+        try {
+            const fullPath = path_1.default.join(this.blobDirectory, blobMetadata.path);
+            if (await this.fileExists(fullPath)) {
+                await fs_1.default.promises.unlink(fullPath);
+                console.log(`🗑️ Deleted blob: ${blobMetadata.path}`);
+                await this.cleanupEmptyDirectories(path_1.default.dirname(fullPath));
+            }
+            else {
+                console.warn(`Warning: Blob file not found for deletion: ${blobMetadata.path}`);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to delete blob: ${error}`);
+        }
+    }
+    async getBlobStats() {
+        this.ensureInitialized();
+        try {
+            const directoryInfo = await this.analyzeDirectory(this.blobDirectory);
+            const availableSpace = await this.getAvailableSpace();
+            return {
+                totalFiles: directoryInfo.totalFiles,
+                totalSizeBytes: directoryInfo.totalSize,
+                averageFileSize: directoryInfo.totalFiles > 0 ? directoryInfo.totalSize / directoryInfo.totalFiles : 0,
+                compressionRatio: 1.0,
+                availableSpaceBytes: availableSpace,
+                directoryStructure: directoryInfo.subdirectories
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to get blob stats: ${error}`);
+        }
+    }
+    async validateBlobIntegrity() {
+        this.ensureInitialized();
+        const result = {
+            isValid: true,
+            corruptedFiles: [],
+            missingFiles: [],
+            orphanedFiles: [],
+            checksumMismatches: []
+        };
+        try {
+            const allFiles = await this.getAllBlobFiles();
+            for (const filePath of allFiles) {
+                try {
+                    const fullPath = path_1.default.join(this.blobDirectory, filePath);
+                    const stats = await fs_1.default.promises.stat(fullPath);
+                    if (stats.size === 0) {
+                        result.corruptedFiles.push(filePath);
+                        result.isValid = false;
+                    }
+                }
+                catch (error) {
+                    result.missingFiles.push(filePath);
+                    result.isValid = false;
+                }
+            }
+            if (result.corruptedFiles.length > 0 || result.missingFiles.length > 0) {
+                console.warn(`⚠️ Blob integrity issues found: ${result.corruptedFiles.length} corrupted, ${result.missingFiles.length} missing`);
+            }
+            else {
+                console.log('✅ Blob integrity validation passed');
+            }
+            return result;
+        }
+        catch (error) {
+            throw new Error(`Failed to validate blob integrity: ${error}`);
+        }
+    }
+    async cleanupOrphanedBlobs(referencedPaths) {
+        this.ensureInitialized();
+        try {
+            const allFiles = await this.getAllBlobFiles();
+            const referencedSet = new Set(referencedPaths);
+            let cleanedCount = 0;
+            for (const filePath of allFiles) {
+                if (!referencedSet.has(filePath)) {
+                    try {
+                        const fullPath = path_1.default.join(this.blobDirectory, filePath);
+                        await fs_1.default.promises.unlink(fullPath);
+                        cleanedCount++;
+                        console.log(`🧹 Cleaned orphaned blob: ${filePath}`);
+                    }
+                    catch (error) {
+                        console.warn(`Warning: Failed to delete orphaned blob ${filePath}:`, error);
+                    }
+                }
+            }
+            if (cleanedCount > 0) {
+                await this.cleanupEmptyDirectories(this.blobDirectory);
+                console.log(`🧹 Cleaned up ${cleanedCount} orphaned blobs`);
+            }
+            return cleanedCount;
+        }
+        catch (error) {
+            throw new Error(`Failed to cleanup orphaned blobs: ${error}`);
+        }
+    }
+    async getAvailableSpace() {
+        try {
+            const testFile = path_1.default.join(this.blobDirectory, '.space-test');
+            await fs_1.default.promises.writeFile(testFile, 'test');
+            await fs_1.default.promises.unlink(testFile);
+            return 10 * 1024 * 1024 * 1024;
+        }
+        catch (error) {
+            console.warn('Unable to check available disk space:', error);
+            return 1024 * 1024 * 1024;
+        }
+    }
+    async close() {
+        this.isInitialized = false;
+        console.log('📁 Filesystem blob storage closed');
+    }
+    ensureInitialized() {
+        if (!this.isInitialized) {
+            throw new Error('FileSystemBlobStorage not initialized');
+        }
+    }
+    async ensureDirectory(dirPath) {
+        try {
+            await fs_1.default.promises.mkdir(dirPath, {
+                recursive: true,
+                mode: this.config.blobs.directoryPermissions
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to create directory ${dirPath}: ${error}`);
+        }
+    }
+    generateBlobPath(sessionId, checkpointId) {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, '0');
+        const sessionPrefix = sessionId.substring(0, 8);
+        return path_1.default.join(String(year), month, sessionPrefix, `${checkpointId}.json.gz`);
+    }
+    async atomicWrite(filePath, data) {
+        if (!this.config.blobs.atomicWrites) {
+            await fs_1.default.promises.writeFile(filePath, data, { mode: this.config.blobs.filePermissions });
+            return;
+        }
+        const tempFile = `${filePath}.tmp.${crypto_1.default.randomUUID()}`;
+        try {
+            await fs_1.default.promises.writeFile(tempFile, data, { mode: this.config.blobs.filePermissions });
+            await fs_1.default.promises.rename(tempFile, filePath);
+        }
+        catch (error) {
+            try {
+                await fs_1.default.promises.unlink(tempFile);
+            }
+            catch (cleanupError) {
+            }
+            throw error;
+        }
+    }
+    calculateChecksum(data) {
+        return crypto_1.default.createHash('sha256').update(data).digest('hex');
+    }
+    async verifyFileIntegrity(filePath, expectedChecksum, expectedSize) {
+        try {
+            const stats = await fs_1.default.promises.stat(filePath);
+            if (stats.size !== expectedSize) {
+                throw new Error(`File size mismatch: expected ${expectedSize}, got ${stats.size}`);
+            }
+            if (this.config.validation.enableChecksumValidation) {
+                const data = await fs_1.default.promises.readFile(filePath);
+                const actualChecksum = this.calculateChecksum(data);
+                if (actualChecksum !== expectedChecksum) {
+                    throw new Error(`Checksum mismatch: expected ${expectedChecksum}, got ${actualChecksum}`);
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`File integrity verification failed: ${error}`);
+        }
+    }
+    async fileExists(filePath) {
+        try {
+            await fs_1.default.promises.access(filePath, fs_1.default.constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async getAllBlobFiles() {
+        const files = [];
+        const walkDirectory = async (dir, basePath = '') => {
+            try {
+                const entries = await fs_1.default.promises.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path_1.default.join(dir, entry.name);
+                    const relativePath = path_1.default.join(basePath, entry.name);
+                    if (entry.isDirectory()) {
+                        await walkDirectory(fullPath, relativePath);
+                    }
+                    else if (entry.isFile() && entry.name.endsWith('.json.gz')) {
+                        files.push(relativePath);
+                    }
+                }
+            }
+            catch (error) {
+                console.warn(`Warning: Failed to read directory ${dir}:`, error);
+            }
+        };
+        await walkDirectory(this.blobDirectory);
+        return files;
+    }
+    async analyzeDirectory(dirPath) {
+        const subdirectories = [];
+        let totalFiles = 0;
+        let totalSize = 0;
+        const analyzeSubDir = async (subDir, relativePath) => {
+            try {
+                const entries = await fs_1.default.promises.readdir(subDir, { withFileTypes: true });
+                let dirFiles = 0;
+                let dirSize = 0;
+                let lastModified;
+                for (const entry of entries) {
+                    const fullPath = path_1.default.join(subDir, entry.name);
+                    if (entry.isFile()) {
+                        const stats = await fs_1.default.promises.stat(fullPath);
+                        dirFiles++;
+                        dirSize += stats.size;
+                        totalFiles++;
+                        totalSize += stats.size;
+                        if (!lastModified || stats.mtime > lastModified) {
+                            lastModified = stats.mtime;
+                        }
+                    }
+                    else if (entry.isDirectory()) {
+                        await analyzeSubDir(fullPath, path_1.default.join(relativePath, entry.name));
+                    }
+                }
+                if (dirFiles > 0) {
+                    subdirectories.push({
+                        path: relativePath,
+                        fileCount: dirFiles,
+                        totalSize: dirSize,
+                        lastModified: lastModified?.toISOString()
+                    });
+                }
+            }
+            catch (error) {
+                console.warn(`Warning: Failed to analyze directory ${subDir}:`, error);
+            }
+        };
+        try {
+            await analyzeSubDir(dirPath, '.');
+        }
+        catch (error) {
+            console.warn(`Warning: Failed to analyze root directory ${dirPath}:`, error);
+        }
+        return { totalFiles, totalSize, subdirectories };
+    }
+    async cleanupEmptyDirectories(startDir) {
+        if (startDir === this.blobDirectory) {
+            return;
+        }
+        try {
+            const entries = await fs_1.default.promises.readdir(startDir);
+            if (entries.length === 0) {
+                await fs_1.default.promises.rmdir(startDir);
+                console.log(`🧹 Removed empty directory: ${path_1.default.relative(this.blobDirectory, startDir)}`);
+                await this.cleanupEmptyDirectories(path_1.default.dirname(startDir));
+            }
+        }
+        catch (error) {
+        }
+    }
+}
+exports.FileSystemBlobStorage = FileSystemBlobStorage;

package/dist/infrastructure/storage/hybrid-context-storage.d.ts

@@ -0,0 +1,29 @@
+import { IContextStorage, IMetadataStorage, IBlobStorage, ContextStorageConfig, StorageStats, ValidationResult } from './context-storage';
+import { CheckpointMetadata, SessionInfo, CompressedBlob } from '../../types/context-types';
+export declare class HybridContextStorage implements IContextStorage {
+    private metadataStorage;
+    private blobStorage;
+    private config;
+    private isInitialized;
+    constructor(metadataStorage: IMetadataStorage, blobStorage: IBlobStorage, config: ContextStorageConfig);
+    initialize(): Promise<void>;
+    saveCheckpoint(metadata: CheckpointMetadata, blob: CompressedBlob): Promise<void>;
+    loadCheckpoint(checkpointId: string): Promise<{
+        metadata: CheckpointMetadata;
+        blob: CompressedBlob;
+    }>;
+    listCheckpoints(sessionId: string, limit?: number, offset?: number): Promise<CheckpointMetadata[]>;
+    deleteCheckpoint(checkpointId: string): Promise<void>;
+    getSession(sessionId: string): Promise<SessionInfo | null>;
+    upsertSession(session: SessionInfo): Promise<void>;
+    deleteSession(sessionId: string): Promise<void>;
+    getStorageStats(): Promise<StorageStats>;
+    getCheckpoint(checkpointId: string): Promise<CheckpointMetadata | null>;
+    validateIntegrity(): Promise<ValidationResult>;
+    close(): Promise<void>;
+    cleanupOrphanedBlobs(): Promise<number>;
+    private updateSessionAccess;
+    private ensureInitialized;
+}
+export declare function createDefaultHybridContextStorage(config?: Partial<ContextStorageConfig>): Promise<HybridContextStorage>;
+export declare function createCustomHybridContextStorage(metadataStorage: IMetadataStorage, blobStorage: IBlobStorage, config: ContextStorageConfig): Promise<HybridContextStorage>;