kist 0.0.0 → 0.1.30

package/js/live/LiveServer.d.ts

@@ -0,0 +1,95 @@
+import { AbstractProcess } from "../core/abstract/AbstractProcess";
+/**
+ * LiveServer class provides functionality to serve static files,
+ * inject live reload scripts into HTML responses, and manage WebSocket
+ * connections to enable live reload capabilities.
+ */
+export declare class LiveServer extends AbstractProcess {
+    /**
+     * Express application
+     */
+    private app;
+    /**
+     * The underlying HTTP server used by the LiveServer.
+     * Handles incoming HTTP requests and serves static files.
+     */
+    private server;
+    /**
+     * The WebSocket server responsible for managing WebSocket connections.
+     * Enables real-time communication with connected clients.
+     */
+    private wss;
+    /**
+     * A set of WebSocket clients currently connected to the server.
+     * Each client represents an active WebSocket connection.
+     */
+    private clients;
+    /**
+     * The port number on which the server is running.
+     * Defaults to 3000 if not specified in the configuration.
+     */
+    private port;
+    /**
+     * The root directory from which static files are served.
+     * Defaults to the "public" folder in the current working directory.
+     */
+    private root;
+    /**
+     * An array of paths to watch for changes.
+     * When a file within these paths changes, the server triggers live reload.
+     */
+    private watchPaths;
+    /**
+     * An array of paths or patterns to ignore during file watching.
+     * Prevents unnecessary reloads caused by changes in these paths.
+     * Defaults to ignoring the "node_modules" directory.
+     */
+    private ignoredPaths;
+    /**
+     * Initializes the LiveServer.
+    //  * @param port - The port on which the server will listen.
+     */
+    constructor();
+    /**
+     * Initializes the HTTP server and WebSocket server.
+     */
+    private initializeServer;
+    /** Logs initialization details for the LiveServer. */
+    private logInitializationDetails;
+    /**
+     * Sets up rate limiting middleware to prevent abuse of HTTP requests.
+     */
+    private setupRateLimiter;
+    /**
+     * Sets up WebSocket handlers to manage client connections.
+     */
+    private setupWebSocketHandlers;
+    /**
+     * Sets up middleware for serving static files and injecting the live
+     * reload script into HTML files.
+     */
+    private setupMiddleware;
+    /**
+     * Middleware function to inject the live reload script into HTML
+     * responses. Prevents directory traversal attacks by sanitizing the
+     * requested file path.
+     * @param req - The HTTP request object.
+     * @param res - The HTTP response object.
+     * @param next - The next middleware function.
+     */
+    private injectLiveReloadScript;
+    /**
+     * Sends a reload signal to all connected WebSocket clients.
+     */
+    reloadClients(): void;
+    /**
+     * Gracefully shuts down the server and all WebSocket connections.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Type guard to check if an error is an instance of NodeJS.ErrnoException.
+     * @param error - The error to check.
+     * @returns True if the error has a `code` property.
+     */
+    private isErrnoException;
+}

package/js/live/LiveServer.js

@@ -0,0 +1,233 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveServer = void 0;
+const express_1 = __importDefault(require("express"));
+const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
+const path_1 = __importDefault(require("path"));
+const ws_1 = require("ws");
+const AbstractProcess_1 = require("../core/abstract/AbstractProcess");
+const ConfigStore_1 = require("../core/config/ConfigStore");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * LiveServer class provides functionality to serve static files,
+ * inject live reload scripts into HTML responses, and manage WebSocket
+ * connections to enable live reload capabilities.
+ */
+class LiveServer extends AbstractProcess_1.AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Initializes the LiveServer.
+    //  * @param port - The port on which the server will listen.
+     */
+    constructor() {
+        super();
+        // Parameters
+        // ========================================================================
+        /**
+         * Express application
+         */
+        this.app = (0, express_1.default)();
+        /**
+         * A set of WebSocket clients currently connected to the server.
+         * Each client represents an active WebSocket connection.
+         */
+        this.clients = new Set();
+        const configStore = ConfigStore_1.ConfigStore.getInstance();
+        const liveReloadOptions = configStore.get("options.live") || {};
+        // Extract and apply live reload options with defaults
+        this.port = liveReloadOptions.port || 3000;
+        this.root = path_1.default.resolve(process.cwd(), liveReloadOptions.root || "public");
+        this.watchPaths = (liveReloadOptions.watchPaths || [
+            "src/**/*",
+            "config/**/*",
+            "pack.yaml",
+        ]).map((p) => path_1.default.resolve(process.cwd(), p));
+        this.ignoredPaths = (liveReloadOptions.ignoredPaths || ["node_modules"]).map((p) => path_1.default.resolve(process.cwd(), p));
+        // Log initialization details
+        this.logInitializationDetails();
+        // Initialize server
+        // this.initializeServer();
+        // Start the HTTP server
+        this.server = this.app.listen(this.port, () => {
+            this.logInfo(`Live Server running at http://localhost:${this.port}`);
+        });
+        // Initialize WebSocket server
+        this.wss = new ws_1.WebSocketServer({ server: this.server });
+        // Set up rate limiting
+        this.setupRateLimiter();
+        // Set up WebSocket handlers
+        this.setupWebSocketHandlers();
+        // Set up middleware
+        this.setupMiddleware();
+    }
+    // Methods
+    // ========================================================================
+    /**
+     * Initializes the HTTP server and WebSocket server.
+     */
+    initializeServer() {
+        // Start the HTTP server
+        this.server = this.app.listen(this.port, () => {
+            this.logInfo(`Live Server running at http://localhost:${this.port}`);
+        });
+        // Initialize WebSocket server
+        this.wss = new ws_1.WebSocketServer({ server: this.server });
+    }
+    /** Logs initialization details for the LiveServer. */
+    logInitializationDetails() {
+        this.logInfo(`LiveServer initialized with port: ${this.port}`);
+        this.logInfo(`Serving static files from: ${this.root}`);
+        this.logInfo(`Watching paths: ${JSON.stringify(this.watchPaths)}`);
+        this.logInfo(`Ignoring paths: ${JSON.stringify(this.ignoredPaths)}`);
+    }
+    /**
+     * Sets up rate limiting middleware to prevent abuse of HTTP requests.
+     */
+    setupRateLimiter() {
+        const limiter = (0, express_rate_limit_1.default)({
+            windowMs: 15 * 60 * 1000, // 15 minutes
+            max: 100, // Limit each IP to 100 requests per windowMs
+            message: "Too many requests from this IP, please try again later.",
+        });
+        this.app.use(limiter);
+    }
+    /**
+     * Sets up WebSocket handlers to manage client connections.
+     */
+    setupWebSocketHandlers() {
+        this.wss.on("connection", (ws) => {
+            this.logInfo("New WebSocket connection established.");
+            this.clients.add(ws);
+            ws.on("message", (message) => {
+                this.logInfo(`WebSocket message received: ${message.toString()}`);
+            });
+            ws.on("close", () => {
+                this.logInfo("WebSocket connection closed.");
+                this.clients.delete(ws);
+            });
+            ws.on("error", (error) => {
+                console.error("WebSocket encountered an error:", error);
+                this.clients.delete(ws);
+            });
+        });
+    }
+    /**
+     * Sets up middleware for serving static files and injecting the live
+     * reload script into HTML files.
+     */
+    setupMiddleware() {
+        // Securely serve static files from the "public" directory
+        // const publicPath = path.resolve(
+        //     __dirname,
+        //     "public"
+        // );
+        this.logInfo(`Resolved public directory: ${this.root}`);
+        this.logInfo(`Serving static files from: ${this.root}`);
+        this.app.use(express_1.default.static(this.root));
+        // Middleware to inject the live reload script into HTML files
+        this.app.use(this.injectLiveReloadScript.bind(this));
+    }
+    /**
+     * Middleware function to inject the live reload script into HTML
+     * responses. Prevents directory traversal attacks by sanitizing the
+     * requested file path.
+     * @param req - The HTTP request object.
+     * @param res - The HTTP response object.
+     * @param next - The next middleware function.
+     */
+    injectLiveReloadScript(req, res, next) {
+        if (req.url.endsWith(".html")) {
+            const sanitizedPath = path_1.default.join(path_1.default.resolve(__dirname, "public"), 
+            // Prevent directory traversal
+            path_1.default.normalize(req.url).replace(/^(\.\.(\/|\\|$))+/g, ""));
+            res.sendFile(sanitizedPath, (err) => {
+                if (err) {
+                    console.error("Error sending HTML file:", err);
+                    next(err);
+                }
+                else {
+                    res.write(`<script>
+                            const ws = new WebSocket("ws://localhost:${this.port}");
+                            ws.onmessage = (event) => {
+                                if (event.data === "reload") {
+                                    this.logInfo("Reloading page...");
+                                    window.location.reload();
+                                }
+                            };
+                        </script>`);
+                    res.end();
+                }
+            });
+        }
+        else {
+            next();
+        }
+    }
+    /**
+     * Sends a reload signal to all connected WebSocket clients.
+     */
+    reloadClients() {
+        this.logInfo("Reloading all connected clients...");
+        this.clients.forEach((client) => {
+            if (client.readyState === ws_1.WebSocket.OPEN) {
+                client.send("reload");
+            }
+        });
+    }
+    /**
+     * Gracefully shuts down the server and all WebSocket connections.
+     */
+    shutdown() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logInfo("Shutting down Live Reload Server...");
+            this.clients.forEach((client) => client.close());
+            this.wss.close();
+            yield new Promise((resolve, reject) => {
+                this.server.close((err) => {
+                    if (err) {
+                        if (this.isErrnoException(err) &&
+                            err.code === "ERR_SERVER_NOT_RUNNING") {
+                            this.logWarn("Server is not running, skipping shutdown.");
+                            resolve();
+                        }
+                        else {
+                            this.logError("Error shutting down server:", err);
+                            reject(err);
+                        }
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+            this.logInfo("Live Reload Server has been shut down.");
+        });
+    }
+    /**
+     * Type guard to check if an error is an instance of NodeJS.ErrnoException.
+     * @param error - The error to check.
+     * @returns True if the error has a `code` property.
+     */
+    isErrnoException(error) {
+        return typeof error === "object" && error !== null && "code" in error;
+    }
+}
+exports.LiveServer = LiveServer;

package/js/live/LiveWatcher.d.ts

@@ -0,0 +1,45 @@
+import { AbstractProcess } from "../core/abstract/AbstractProcess";
+/**
+ * LiveWatcher is a utility class for monitoring file and directory changes.
+ * It leverages the `chokidar` library to efficiently detect file changes and
+ * trigger appropriate callbacks.
+ */
+export declare class LiveWatcher extends AbstractProcess {
+    /**
+     * The chokidar file watcher instance.
+     */
+    private watcher;
+    private pathsToWatch;
+    private ignoredPaths;
+    private onChange;
+    /**
+     * Creates an instance of LiveWatcher.
+     * @param pathsToWatch - An array of paths to monitor for changes.
+     * @param ignoredPaths - A regular expression to specify paths or patterns
+     * to exclude from watching.
+     * @param onChange - A callback function that is executed when a file
+     * change is detected.
+     */
+    constructor(onChange: (filePath: string) => void);
+    /**
+     * Initializes and configures the chokidar watcher to monitor files and
+     * directories.
+     */
+    private setupWatchers;
+    /**
+     * Starts the file watcher if it is not already running. If the watcher
+     * was stopped previously, it re-initializes the watcher.
+     */
+    startWatching(): void;
+    /**
+     * Stops the file watcher and releases its resources. This is useful when
+     * you need to clean up or reinitialize the watcher.
+     */
+    stopWatching(): Promise<void>;
+    /**
+     * Restarts the file watcher by first stopping the existing watcher (if
+     * any) and then starting a new one. This can be useful in scenarios where
+     * watcher configurations or paths have changed.
+     */
+    restartWatcher(): Promise<void>;
+}

package/js/live/LiveWatcher.js

@@ -0,0 +1,140 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveWatcher = void 0;
+const chokidar_1 = __importDefault(require("chokidar"));
+const AbstractProcess_1 = require("../core/abstract/AbstractProcess");
+const ConfigStore_1 = require("../core/config/ConfigStore");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * LiveWatcher is a utility class for monitoring file and directory changes.
+ * It leverages the `chokidar` library to efficiently detect file changes and
+ * trigger appropriate callbacks.
+ */
+class LiveWatcher extends AbstractProcess_1.AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Creates an instance of LiveWatcher.
+     * @param pathsToWatch - An array of paths to monitor for changes.
+     * @param ignoredPaths - A regular expression to specify paths or patterns
+     * to exclude from watching.
+     * @param onChange - A callback function that is executed when a file
+     * change is detected.
+     */
+    constructor(
+    // private pathsToWatch: string[],
+    // private ignoredPaths: RegExp,
+    onChange) {
+        var _a, _b;
+        super();
+        // Parameters
+        // ========================================================================
+        /**
+         * The chokidar file watcher instance.
+         */
+        this.watcher = null;
+        // Retrieve live reload configuration from ConfigStore
+        const liveReloadOptions = ConfigStore_1.ConfigStore.getInstance().get("options.live") || {};
+        this.pathsToWatch = (_a = liveReloadOptions.watchPaths) !== null && _a !== void 0 ? _a : [
+            "src/**/*",
+            "config/**/*",
+            "pack.yaml",
+        ];
+        this.ignoredPaths = (_b = liveReloadOptions.ignoredPaths) !== null && _b !== void 0 ? _b : ["node_modules"];
+        this.onChange = onChange;
+        this.startWatching();
+    }
+    // Methods
+    // ========================================================================
+    /**
+     * Initializes and configures the chokidar watcher to monitor files and
+     * directories.
+     */
+    setupWatchers() {
+        if (!this.watcher)
+            return;
+        this.watcher
+            .on("ready", () => {
+            this.logInfo("File watching is active. Waiting for changes...");
+        })
+            .on("change", (filePath) => {
+            this.logInfo(`File changed: ${filePath}`);
+            try {
+                this.onChange(filePath);
+            }
+            catch (error) {
+                this.logError(`Error handling file change for ${filePath}:`, error);
+            }
+        })
+            .on("error", (error) => {
+            this.logError("Watcher encountered an error:", error);
+        });
+    }
+    /**
+     * Starts the file watcher if it is not already running. If the watcher
+     * was stopped previously, it re-initializes the watcher.
+     */
+    startWatching() {
+        if (this.watcher) {
+            this.logInfo("Watcher is already running.");
+            return;
+        }
+        this.logInfo("Starting file watcher...");
+        this.watcher = chokidar_1.default.watch(this.pathsToWatch, {
+            ignored: this.ignoredPaths,
+            persistent: true,
+            // Prevents initial "add" events on startup
+            ignoreInitial: true,
+            awaitWriteFinish: {
+                // Polling interval to check for file stability
+                pollInterval: 100,
+                // Waits for file to finish writing
+                stabilityThreshold: 100,
+            },
+        });
+        this.setupWatchers();
+    }
+    /**
+     * Stops the file watcher and releases its resources. This is useful when
+     * you need to clean up or reinitialize the watcher.
+     */
+    stopWatching() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.watcher) {
+                yield this.watcher.close();
+                this.logInfo("File watching has been stopped.");
+                this.watcher = null;
+            }
+        });
+    }
+    /**
+     * Restarts the file watcher by first stopping the existing watcher (if
+     * any) and then starting a new one. This can be useful in scenarios where
+     * watcher configurations or paths have changed.
+     */
+    restartWatcher() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logInfo("Restarting file watcher...");
+            yield this.stopWatching();
+            this.startWatching();
+        });
+    }
+}
+exports.LiveWatcher = LiveWatcher;

package/js/logger/Logger.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Logger class for handling console messages.
+ * Singleton instance ensures consistent logging behavior throughout the
+ * application.
+ */
+export declare class Logger {
+    /**
+     * Singleton instance
+     */
+    private static instance;
+    /**
+     * Current log level
+     */
+    private logLevel;
+    /**
+     * Private constructor to enforce singleton pattern.
+     * @param logLevel - The log level for controlling log output.
+     */
+    private constructor();
+    /**
+     * Retrieves the singleton instance of Logger.
+     * Initializes a non-verbose Logger instance if it hasn't been explicitly
+     * initialized.
+     *
+     * @returns The Logger instance.
+     */
+    static getInstance(logLevel?: "debug" | "info" | "warn" | "error"): Logger;
+    /**
+     * Resets the Logger instance.
+     * Useful for testing or reinitializing the Logger during runtime.
+     */
+    static resetInstance(): void;
+    /**
+     * Logs a message with a specific level if it meets the current log level.
+     *
+     * @param level - The log level (e.g., "INFO", "WARN", "ERROR").
+     * @param context - The context or class name where the log originates.
+     * @param message - The message content to log.
+     * @param fgStyle - The foreground color style to apply to the log level.
+     * @param bgStyle - The background color style to apply to the log level (default is reset).
+     */
+    private log;
+    /**
+     * Determines if a log should be displayed based on the current log level.
+     *
+     * @param level - The level of the log being checked.
+     * @returns True if the log should be displayed, otherwise false.
+     */
+    private shouldLog;
+    /**
+     * Logs an informational message.
+     *
+     * @param context - The originating class or module.
+     * @param message - The informational message to log.
+     */
+    logInfo(context: string, message: string): void;
+    /**
+     * Logs a warning message.
+     *
+     * @param context - The originating class or module.
+     * @param message - The warning message to log.
+     */
+    logWarn(context: string, message: string): void;
+    /**
+     * Logs an error message.
+     *
+     * @param context - The originating class or module.
+     * @param message - The error message to log.
+     * @param error - (Optional) Additional error details.
+     */
+    logError(context: string, message: string, error?: unknown): void;
+    /**
+     * Logs a debug message.
+     *
+     * @param context - The originating class or module.
+     * @param message - The debug message to log.
+     */
+    logDebug(context: string, message: string): void;
+    /**
+     * Sets the log level dynamically.
+     *
+     * @param level - The log level to set (e.g., "debug", "info").
+     */
+    setLogLevel(level: "debug" | "info" | "warn" | "error"): void;
+    /**
+     * Formats an error message for logging.
+     * Combines a base message with additional error details if available.
+     *
+     * @param message - The base error message.
+     * @param error - Additional error information, such as an Error object.
+     * @returns A formatted string combining the message and error details.
+     */
+    private formatError;
+}