@t1mmen/srtd 0.0.0-next-20251227000343

package/dist/services/DatabaseService.d.ts

@@ -0,0 +1,113 @@
+/**
+ * DatabaseService - Centralized database connection and SQL execution service
+ * Handles connection pooling, retry logic, and SQL execution with transaction management
+ */
+import { EventEmitter } from 'node:events';
+import pg from 'pg';
+import type { CLIConfig, MigrationError } from '../types.js';
+export interface DatabaseServiceConfig {
+    connectionString: string;
+    connectionTimeoutMillis?: number;
+    maxConnections?: number;
+    idleTimeoutMillis?: number;
+    maxUses?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    wrapInTransaction?: boolean;
+}
+export interface DatabaseConnection {
+    isConnected: boolean;
+    isChecking: boolean;
+    error?: string;
+}
+export interface ConnectionStats {
+    total: number;
+    idle: number;
+    active: number;
+}
+export declare enum DatabaseErrorType {
+    CONNECTION_ERROR = "CONNECTION_ERROR",
+    SYNTAX_ERROR = "SYNTAX_ERROR",
+    CONSTRAINT_VIOLATION = "CONSTRAINT_VIOLATION",
+    TIMEOUT_ERROR = "TIMEOUT_ERROR",
+    TRANSACTION_ERROR = "TRANSACTION_ERROR",
+    POOL_EXHAUSTED = "POOL_EXHAUSTED",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+export interface DatabaseError {
+    type: DatabaseErrorType;
+    message: string;
+    originalError?: Error;
+    code?: string;
+    detail?: string;
+}
+export interface SqlExecutionResult {
+    success: boolean;
+    error?: string;
+    databaseError?: DatabaseError;
+    rows?: unknown[];
+    rowCount?: number;
+    data?: unknown;
+}
+export interface ExecutionConfig {
+    templateName?: string;
+    useTransaction?: boolean;
+    silent?: boolean;
+    parameters?: unknown[];
+    isolationLevel?: 'READ UNCOMMITTED' | 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE';
+}
+export declare class DatabaseService extends EventEmitter {
+    private config;
+    private pool;
+    private connectionAttempts;
+    private disposed;
+    constructor(config: DatabaseServiceConfig);
+    /**
+     * Categorize database errors for better error handling
+     */
+    private categorizeError;
+    /**
+     * Create and configure database connection pool
+     */
+    private createPool;
+    /**
+     * Establish database connection with retry logic
+     */
+    private retryConnection;
+    /**
+     * Get a database connection with retry logic
+     */
+    connect(params?: {
+        silent?: boolean;
+    }): Promise<pg.PoolClient>;
+    /**
+     * Test database connectivity
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Execute SQL with optional transaction wrapping and parameterized queries
+     * Core method for running template content or any SQL
+     */
+    executeSQL(sql: string, config?: ExecutionConfig): Promise<SqlExecutionResult>;
+    /**
+     * Execute SQL and return migration-compatible result
+     * Used by migration/template application logic
+     */
+    executeMigration(content: string, templateName: string, silent?: boolean): Promise<true | MigrationError>;
+    /**
+     * Get connection pool statistics
+     */
+    getConnectionStats(): ConnectionStats | null;
+    /**
+     * Gracefully close all database connections
+     */
+    dispose(): Promise<void>;
+    /**
+     * Create DatabaseService from CLI config
+     */
+    static fromConfig(config: CLIConfig): DatabaseService;
+    /**
+     * Setup process termination handlers for graceful shutdown
+     */
+    private setupProcessHandlers;
+}

package/dist/services/DatabaseService.js

@@ -0,0 +1,343 @@
+/**
+ * DatabaseService - Centralized database connection and SQL execution service
+ * Handles connection pooling, retry logic, and SQL execution with transaction management
+ */
+import { EventEmitter } from 'node:events';
+import pg from 'pg';
+import { logger } from '../utils/logger.js';
+export var DatabaseErrorType;
+(function (DatabaseErrorType) {
+    DatabaseErrorType["CONNECTION_ERROR"] = "CONNECTION_ERROR";
+    DatabaseErrorType["SYNTAX_ERROR"] = "SYNTAX_ERROR";
+    DatabaseErrorType["CONSTRAINT_VIOLATION"] = "CONSTRAINT_VIOLATION";
+    DatabaseErrorType["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+    DatabaseErrorType["TRANSACTION_ERROR"] = "TRANSACTION_ERROR";
+    DatabaseErrorType["POOL_EXHAUSTED"] = "POOL_EXHAUSTED";
+    DatabaseErrorType["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(DatabaseErrorType || (DatabaseErrorType = {}));
+export class DatabaseService extends EventEmitter {
+    config;
+    pool;
+    connectionAttempts = 0;
+    disposed = false;
+    constructor(config) {
+        super();
+        this.config = {
+            connectionTimeoutMillis: 5000,
+            maxConnections: 6, // Default maxRetries * 2
+            idleTimeoutMillis: 2000,
+            maxUses: 500,
+            maxRetries: 3,
+            retryDelayMs: 500,
+            wrapInTransaction: false,
+            ...config,
+        };
+        // Handle process termination
+        this.setupProcessHandlers();
+    }
+    /**
+     * Categorize database errors for better error handling
+     */
+    categorizeError(error) {
+        const pgError = error;
+        const errorCode = pgError?.code;
+        const errorMessage = pgError?.message || String(error);
+        // Connection errors
+        if (errorCode === 'ECONNREFUSED' || errorCode === 'ENOTFOUND' || errorCode === 'ECONNRESET') {
+            return {
+                type: DatabaseErrorType.CONNECTION_ERROR,
+                message: 'Database connection failed',
+                originalError: error instanceof Error ? error : new Error(String(error)),
+                code: errorCode,
+                detail: errorMessage,
+            };
+        }
+        // Pool exhaustion
+        if (errorMessage.includes('pool is exhausted') || errorMessage.includes('too many clients')) {
+            return {
+                type: DatabaseErrorType.POOL_EXHAUSTED,
+                message: 'Database connection pool exhausted',
+                originalError: error instanceof Error ? error : new Error(String(error)),
+                code: errorCode,
+                detail: errorMessage,
+            };
+        }
+        // Timeout errors
+        if (errorCode === 'ETIMEOUT' || errorMessage.includes('timeout')) {
+            return {
+                type: DatabaseErrorType.TIMEOUT_ERROR,
+                message: 'Database operation timed out',
+                originalError: error instanceof Error ? error : new Error(String(error)),
+                code: errorCode,
+                detail: errorMessage,
+            };
+        }
+        // PostgreSQL specific error codes
+        if (errorCode) {
+            // Syntax errors (42xxx)
+            if (errorCode.startsWith('42')) {
+                return {
+                    type: DatabaseErrorType.SYNTAX_ERROR,
+                    message: 'SQL syntax error',
+                    originalError: error instanceof Error ? error : new Error(String(error)),
+                    code: errorCode,
+                    detail: errorMessage,
+                };
+            }
+            // Constraint violations (23xxx)
+            if (errorCode.startsWith('23')) {
+                return {
+                    type: DatabaseErrorType.CONSTRAINT_VIOLATION,
+                    message: 'Database constraint violation',
+                    originalError: error instanceof Error ? error : new Error(String(error)),
+                    code: errorCode,
+                    detail: errorMessage,
+                };
+            }
+            // Transaction errors (25xxx, 40xxx)
+            if (errorCode.startsWith('25') || errorCode.startsWith('40')) {
+                return {
+                    type: DatabaseErrorType.TRANSACTION_ERROR,
+                    message: 'Transaction error',
+                    originalError: error instanceof Error ? error : new Error(String(error)),
+                    code: errorCode,
+                    detail: errorMessage,
+                };
+            }
+        }
+        // Default to unknown error
+        return {
+            type: DatabaseErrorType.UNKNOWN_ERROR,
+            message: errorMessage,
+            originalError: error instanceof Error ? error : new Error(String(error)),
+            code: errorCode,
+            detail: errorMessage,
+        };
+    }
+    /**
+     * Create and configure database connection pool
+     */
+    async createPool() {
+        // Only create a new pool if one doesn't exist or has been ended
+        if (!this.pool || this.pool.ended) {
+            this.pool = new pg.Pool({
+                connectionString: this.config.connectionString,
+                connectionTimeoutMillis: this.config.connectionTimeoutMillis,
+                max: this.config.maxConnections,
+                idleTimeoutMillis: this.config.idleTimeoutMillis,
+                maxUses: this.config.maxUses,
+            });
+            // Handle pool errors
+            this.pool.on('error', err => {
+                const errorMessage = `Unexpected pool error: ${err}`;
+                logger.error(errorMessage);
+                this.emit('error', new Error(errorMessage));
+            });
+            this.emit('pool:created');
+        }
+        return this.pool;
+    }
+    /**
+     * Establish database connection with retry logic
+     */
+    async retryConnection(params) {
+        const { silent = true } = params || {};
+        this.connectionAttempts++;
+        logger.debug(`Connection attempt ${this.connectionAttempts}`);
+        try {
+            const currentPool = await this.createPool();
+            const client = await currentPool.connect();
+            this.emit('connection:established');
+            return client;
+        }
+        catch (err) {
+            if (this.connectionAttempts < (this.config.maxRetries ?? 3)) {
+                if (!silent) {
+                    logger.warn(`Connection failed, retrying in ${this.config.retryDelayMs}ms...`);
+                }
+                await new Promise(resolve => setTimeout(resolve, this.config.retryDelayMs));
+                return this.retryConnection(params);
+            }
+            const databaseError = this.categorizeError(err);
+            const error = new Error(`Database connection failed after ${this.config.maxRetries} attempts: ${databaseError.message}`);
+            this.emit('connection:failed', { error, databaseError });
+            throw error;
+        }
+    }
+    /**
+     * Get a database connection with retry logic
+     */
+    async connect(params) {
+        this.connectionAttempts = 0;
+        return await this.retryConnection(params);
+    }
+    /**
+     * Test database connectivity
+     */
+    async testConnection() {
+        try {
+            const client = await this.connect({ silent: true });
+            try {
+                await client.query('SELECT 1');
+                return true;
+            }
+            finally {
+                client.release();
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Execute SQL with optional transaction wrapping and parameterized queries
+     * Core method for running template content or any SQL
+     */
+    async executeSQL(sql, config) {
+        const { templateName = 'unknown', useTransaction = this.config.wrapInTransaction, silent = false, parameters = [], isolationLevel, } = config || {};
+        const client = await this.connect({ silent });
+        try {
+            if (useTransaction) {
+                await client.query('BEGIN');
+                // Set isolation level if specified
+                if (isolationLevel) {
+                    await client.query(`SET TRANSACTION ISOLATION LEVEL ${isolationLevel}`);
+                }
+                // Use advisory lock for templates to prevent concurrent modifications
+                if (templateName !== 'unknown') {
+                    const lockKey = Math.abs(Buffer.from(templateName).reduce((acc, byte) => acc + byte, 0));
+                    await client.query(`SELECT pg_advisory_xact_lock(${lockKey}::bigint)`);
+                }
+            }
+            // Execute with or without parameters for security
+            const result = parameters.length > 0 ? await client.query(sql, parameters) : await client.query(sql);
+            if (useTransaction) {
+                await client.query('COMMIT');
+            }
+            if (!silent) {
+                logger.success(`SQL executed successfully for ${templateName}`);
+            }
+            this.emit('sql:success', { templateName, rowCount: result.rowCount });
+            return {
+                success: true,
+                rows: result.rows,
+                rowCount: result.rowCount ?? 0,
+                data: result.rows,
+            };
+        }
+        catch (error) {
+            if (useTransaction) {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch (rollbackError) {
+                    logger.error(`Rollback failed: ${rollbackError}`);
+                }
+            }
+            const databaseError = this.categorizeError(error);
+            const errorMessage = databaseError.message;
+            if (!silent) {
+                logger.error(`SQL execution failed for ${templateName}: ${errorMessage} (${databaseError.type})`);
+            }
+            this.emit('sql:error', { templateName, error: errorMessage, errorType: databaseError.type });
+            return {
+                success: false,
+                error: errorMessage,
+                databaseError,
+            };
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Execute SQL and return migration-compatible result
+     * Used by migration/template application logic
+     */
+    async executeMigration(content, templateName, silent = false) {
+        const result = await this.executeSQL(content, {
+            templateName,
+            useTransaction: true,
+            silent,
+            isolationLevel: 'READ COMMITTED', // Safe default for migrations
+        });
+        if (result.success) {
+            return true;
+        }
+        return {
+            file: templateName,
+            error: result.error || 'Unknown error',
+            templateName,
+        };
+    }
+    /**
+     * Get connection pool statistics
+     */
+    getConnectionStats() {
+        if (!this.pool)
+            return null;
+        return {
+            total: this.pool.totalCount,
+            idle: this.pool.idleCount,
+            active: this.pool.totalCount - this.pool.idleCount,
+        };
+    }
+    /**
+     * Gracefully close all database connections
+     */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.pool && !this.pool.ended) {
+            try {
+                // Suppress errors during shutdown
+                this.pool.on('error', () => {
+                    // Empty handler on purpose
+                });
+                // End the pool with a timeout
+                const endPromise = this.pool.end();
+                const timeoutPromise = new Promise(resolve => {
+                    setTimeout(() => {
+                        logger.debug('Pool end timed out, proceeding anyway');
+                        resolve();
+                    }, 1000);
+                });
+                await Promise.race([endPromise, timeoutPromise]);
+                this.emit('pool:closed');
+            }
+            catch (e) {
+                logger.error(`Pool end error: ${e}`);
+                // Don't re-throw disposal errors, just log them
+            }
+            finally {
+                this.pool = undefined; // Important: clear the pool reference
+            }
+        }
+        // Remove all listeners
+        this.removeAllListeners();
+    }
+    /**
+     * Create DatabaseService from CLI config
+     */
+    static fromConfig(config) {
+        return new DatabaseService({
+            connectionString: config.pgConnection,
+            wrapInTransaction: config.wrapInTransaction,
+        });
+    }
+    /**
+     * Setup process termination handlers for graceful shutdown
+     */
+    setupProcessHandlers() {
+        // Only add handlers if we don't already have too many
+        if (process.listenerCount('SIGTERM') < 10 && process.listenerCount('SIGINT') < 10) {
+            const cleanup = () => {
+                void this.dispose().then(() => process.exit(0));
+            };
+            process.on('SIGTERM', cleanup);
+            process.on('SIGINT', cleanup);
+        }
+    }
+}
+//# sourceMappingURL=DatabaseService.js.map

package/dist/services/DatabaseService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseService.js","sourceRoot":"","sources":["../../src/services/DatabaseService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAyB5C,MAAM,CAAN,IAAY,iBAQX;AARD,WAAY,iBAAiB;IAC3B,0DAAqC,CAAA;IACrC,kDAA6B,CAAA;IAC7B,kEAA6C,CAAA;IAC7C,oDAA+B,CAAA;IAC/B,4DAAuC,CAAA;IACvC,sDAAiC,CAAA;IACjC,oDAA+B,CAAA;AACjC,CAAC,EARW,iBAAiB,KAAjB,iBAAiB,QAQ5B;AA2BD,MAAM,OAAO,eAAgB,SAAQ,YAAY;IACvC,MAAM,CAAwB;IAC9B,IAAI,CAAsB;IAC1B,kBAAkB,GAAG,CAAC,CAAC;IACvB,QAAQ,GAAG,KAAK,CAAC;IAEzB,YAAY,MAA6B;QACvC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,MAAM,GAAG;YACZ,uBAAuB,EAAE,IAAI;YAC7B,cAAc,EAAE,CAAC,EAAE,yBAAyB;YAC5C,iBAAiB,EAAE,IAAI;YACvB,OAAO,EAAE,GAAG;YACZ,UAAU,EAAE,CAAC;YACb,YAAY,EAAE,GAAG;YACjB,iBAAiB,EAAE,KAAK;YACxB,GAAG,MAAM;SACV,CAAC;QAEF,6BAA6B;QAC7B,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACK,eAAe,CAAC,KAAc;QACpC,MAAM,OAAO,GAAG,KAA4C,CAAC;QAC7D,MAAM,SAAS,GAAG,OAAO,EAAE,IAAI,CAAC;QAChC,MAAM,YAAY,GAAG,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;QAEvD,oBAAoB;QACpB,IAAI,SAAS,KAAK,cAAc,IAAI,SAAS,KAAK,WAAW,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;YAC5F,OAAO;gBACL,IAAI,EAAE,iBAAiB,CAAC,gBAAgB;gBACxC,OAAO,EAAE,4BAA4B;gBACrC,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACxE,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,YAAY;aACrB,CAAC;QACJ,CAAC;QAED,kBAAkB;QAClB,IAAI,YAAY,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAC5F,OAAO;gBACL,IAAI,EAAE,iBAAiB,CAAC,cAAc;gBACtC,OAAO,EAAE,oCAAoC;gBAC7C,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACxE,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,YAAY;aACrB,CAAC;QACJ,CAAC;QAED,iBAAiB;QACjB,IAAI,SAAS,KAAK,UAAU,IAAI,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACjE,OAAO;gBACL,IAAI,EAAE,iBAAiB,CAAC,aAAa;gBACrC,OAAO,EAAE,8BAA8B;gBACvC,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACxE,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,YAAY;aACrB,CAAC;QACJ,CAAC;QAED,kCAAkC;QAClC,IAAI,SAAS,EAAE,CAAC;YACd,wBAAwB;YACxB,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,OAAO;oBACL,IAAI,EAAE,iBAAiB,CAAC,YAAY;oBACpC,OAAO,EAAE,kBAAkB;oBAC3B,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACxE,IAAI,EAAE,SAAS;oBACf,MAAM,EAAE,YAAY;iBACrB,CAAC;YACJ,CAAC;YAED,gCAAgC;YAChC,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,OAAO;oBACL,IAAI,EAAE,iBAAiB,CAAC,oBAAoB;oBAC5C,OAAO,EAAE,+BAA+B;oBACxC,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACxE,IAAI,EAAE,SAAS;oBACf,MAAM,EAAE,YAAY;iBACrB,CAAC;YACJ,CAAC;YAED,oCAAoC;YACpC,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7D,OAAO;oBACL,IAAI,EAAE,iBAAiB,CAAC,iBAAiB;oBACzC,OAAO,EAAE,mBAAmB;oBAC5B,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACxE,IAAI,EAAE,SAAS;oBACf,MAAM,EAAE,YAAY;iBACrB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,2BAA2B;QAC3B,OAAO;YACL,IAAI,EAAE,iBAAiB,CAAC,aAAa;YACrC,OAAO,EAAE,YAAY;YACrB,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACxE,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,YAAY;SACrB,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,UAAU;QACtB,gEAAgE;QAChE,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC;gBACtB,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB;gBAC9C,uBAAuB,EAAE,IAAI,CAAC,MAAM,CAAC,uBAAuB;gBAC5D,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;gBAC/B,iBAAiB,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;gBAChD,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;aAC7B,CAAC,CAAC;YAEH,qBAAqB;YACrB,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE;gBAC1B,MAAM,YAAY,GAAG,0BAA0B,GAAG,EAAE,CAAC;gBACrD,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;gBAC3B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;YAC9C,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe,CAAC,MAA6B;QACzD,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,MAAM,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,MAAM,CAAC,KAAK,CAAC,sBAAsB,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;QAE9D,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YAC5C,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;YACpC,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,IAAI,CAAC,kBAAkB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC,EAAE,CAAC;gBAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,MAAM,CAAC,IAAI,CAAC,kCAAkC,IAAI,CAAC,MAAM,CAAC,YAAY,OAAO,CAAC,CAAC;gBACjF,CAAC;gBACD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;gBAC5E,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YACtC,CAAC;YACD,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;YAChD,MAAM,KAAK,GAAG,IAAI,KAAK,CACrB,oCAAoC,IAAI,CAAC,MAAM,CAAC,UAAU,cAAc,aAAa,CAAC,OAAO,EAAE,CAChG,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;YACzD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,MAA6B;QACzC,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;QAC5B,OAAO,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc;QAClB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YACpD,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBAC/B,OAAO,IAAI,CAAC;YACd,CAAC;oBAAS,CAAC;gBACT,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,GAAW,EAAE,MAAwB;QACpD,MAAM,EACJ,YAAY,GAAG,SAAS,EACxB,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAC9C,MAAM,GAAG,KAAK,EACd,UAAU,GAAG,EAAE,EACf,cAAc,GACf,GAAG,MAAM,IAAI,EAAE,CAAC;QAEjB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QAE9C,IAAI,CAAC;YACH,IAAI,cAAc,EAAE,CAAC;gBACnB,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAE5B,mCAAmC;gBACnC,IAAI,cAAc,EAAE,CAAC;oBACnB,MAAM,MAAM,CAAC,KAAK,CAAC,mCAAmC,cAAc,EAAE,CAAC,CAAC;gBAC1E,CAAC;gBAED,sEAAsE;gBACtE,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;oBAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;oBACzF,MAAM,MAAM,CAAC,KAAK,CAAC,gCAAgC,OAAO,WAAW,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC;YAED,kDAAkD;YAClD,MAAM,MAAM,GACV,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAExF,IAAI,cAAc,EAAE,CAAC;gBACnB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC/B,CAAC;YAED,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,CAAC,OAAO,CAAC,iCAAiC,YAAY,EAAE,CAAC,CAAC;YAClE,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;YAEtE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC;gBAC9B,IAAI,EAAE,MAAM,CAAC,IAAI;aAClB,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,cAAc,EAAE,CAAC;gBACnB,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBACjC,CAAC;gBAAC,OAAO,aAAa,EAAE,CAAC;oBACvB,MAAM,CAAC,KAAK,CAAC,oBAAoB,aAAa,EAAE,CAAC,CAAC;gBACpD,CAAC;YACH,CAAC;YAED,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;YAClD,MAAM,YAAY,GAAG,aAAa,CAAC,OAAO,CAAC;YAE3C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,CAAC,KAAK,CACV,4BAA4B,YAAY,KAAK,YAAY,KAAK,aAAa,CAAC,IAAI,GAAG,CACpF,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;YAE7F,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,YAAY;gBACnB,aAAa;aACd,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,gBAAgB,CACpB,OAAe,EACf,YAAoB,EACpB,MAAM,GAAG,KAAK;QAEd,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE;YAC5C,YAAY;YACZ,cAAc,EAAE,IAAI;YACpB,MAAM;YACN,cAAc,EAAE,gBAAgB,EAAE,8BAA8B;SACjE,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO;YACL,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,eAAe;YACtC,YAAY;SACb,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,kBAAkB;QAChB,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QAC5B,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS;YACzB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS;SACnD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAErB,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,kCAAkC;gBAClC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;oBACzB,2BAA2B;gBAC7B,CAAC,CAAC,CAAC;gBAEH,8BAA8B;gBAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;gBACnC,MAAM,cAAc,GAAG,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;oBACjD,UAAU,CAAC,GAAG,EAAE;wBACd,MAAM,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;wBACtD,OAAO,EAAE,CAAC;oBACZ,CAAC,EAAE,IAAI,CAAC,CAAC;gBACX,CAAC,CAAC,CAAC;gBAEH,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;gBACjD,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAC3B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;gBACrC,gDAAgD;YAClD,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC,sCAAsC;YAC/D,CAAC;QACH,CAAC;QAED,uBAAuB;QACvB,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAiB;QACjC,OAAO,IAAI,eAAe,CAAC;YACzB,gBAAgB,EAAE,MAAM,CAAC,YAAY;YACrC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;SAC5C,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,oBAAoB;QAC1B,sDAAsD;QACtD,IAAI,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC;YAClF,MAAM,OAAO,GAAG,GAAG,EAAE;gBACnB,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAClD,CAAC,CAAC;YAEF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC/B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;CACF"}

package/dist/services/FileSystemService.d.ts

@@ -0,0 +1,100 @@
+/**
+ * FileSystemService - Handles all file system operations for templates
+ * Decoupled from business logic, only handles raw file operations
+ */
+import { EventEmitter } from 'node:events';
+import type { Stats } from 'node:fs';
+export interface FileSystemConfig {
+    baseDir: string;
+    templateDir: string;
+    filter: string;
+    migrationDir: string;
+    watchOptions?: {
+        ignoreInitial?: boolean;
+        stabilityThreshold?: number;
+        pollInterval?: number;
+    };
+}
+export interface TemplateFile {
+    path: string;
+    name: string;
+    content: string;
+    hash: string;
+    relativePath: string;
+}
+export interface WatchEvent {
+    type: 'added' | 'changed' | 'removed';
+    path: string;
+    relativePath: string;
+    name: string;
+}
+export declare class FileSystemService extends EventEmitter {
+    private config;
+    private watcher;
+    private debouncedHandlers;
+    constructor(config: FileSystemConfig);
+    /**
+     * Find all template files matching the configured pattern
+     */
+    findTemplates(): Promise<string[]>;
+    /**
+     * Read a template file and return its content with metadata
+     */
+    readTemplate(templatePath: string): Promise<TemplateFile>;
+    /**
+     * Check if a file exists
+     */
+    fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Write content to a file
+     */
+    writeFile(filePath: string, content: string): Promise<void>;
+    /**
+     * Delete a file
+     */
+    deleteFile(filePath: string): Promise<void>;
+    /**
+     * Rename a file
+     */
+    renameFile(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Get file stats
+     */
+    getFileStats(filePath: string): Promise<Stats>;
+    /**
+     * Calculate MD5 hash of content
+     */
+    private calculateHash;
+    /**
+     * Watch templates for changes
+     */
+    watchTemplates(): Promise<void>;
+    /**
+     * Stop watching templates
+     */
+    stopWatching(): Promise<void>;
+    /**
+     * Emit watch event with debouncing
+     */
+    private debouncedEmit;
+    /**
+     * Emit a watch event
+     */
+    private emitWatchEvent;
+    /**
+     * Clean up resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * Get migration file path for a template
+     */
+    getMigrationPath(templateName: string, timestamp: string): string;
+    /**
+     * List all migration files
+     */
+    listMigrations(): Promise<string[]>;
+    /**
+     * Read a migration file
+     */
+    readMigration(migrationPath: string): Promise<string>;
+}