kist 0.0.0 → 0.1.30

package/ts/kist.ts

@@ -0,0 +1,161 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { AbstractProcess } from "./core/abstract/AbstractProcess";
+import { ConfigStore } from "./core/config/ConfigStore";
+import { ActionRegistry } from "./core/pipeline/ActionRegistry";
+import { PipelineManager } from "./core/pipeline/PipelineManager";
+import { LiveServer } from "./live/LiveServer";
+import { LiveWatcher } from "./live/LiveWatcher";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * The Kist class encapsulates the kist CLI functionality.
+ * It manages the pipeline execution, configuration loading, and live reload.
+ */
+export class Kist extends AbstractProcess {
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Constructs the Kist class instance and initializes necessary components.
+     */
+    constructor() {
+        super();
+        this.logDebug("Kist initialized.");
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Executes the Kist workflow.
+     *
+     * This method orchestrates the execution of the Kist pipeline, starting
+     * from initializing the ActionRegistry, loading configuration settings,
+     * running the pipeline stages through the `PipelineManager`, and
+     * optionally enabling live reload for real-time updates.
+     *
+     * @returns {Promise<void>} Resolves when the workflow completes successfully.
+     * @example
+     * const Kist = new Kist();
+     * Kist.run().then(() => console.log("Pipeline execution complete."));
+     */
+    public async run(): Promise<void> {
+        this.logInfo("Starting Kist workflow...");
+
+        try {
+            // Initialize the ActionRegistry with available actions
+            this.initializeActionRegistry();
+
+            // Create and run the PipelineManager
+            const liveReloadEnabled = ConfigStore.getInstance().get<boolean>(
+                "options.live.enabled",
+            );
+            const liveReloadServer = liveReloadEnabled
+                ? new LiveServer()
+                : null;
+
+            const pipelineManager = new PipelineManager(liveReloadServer!);
+            await pipelineManager.runPipeline();
+
+            // Setup live reload if enabled
+            if (liveReloadEnabled) {
+                this.setupLiveReload(pipelineManager, liveReloadServer!);
+            }
+        } catch (error) {
+            this.handleError(error);
+        }
+    }
+
+    /**
+     * Initializes the ActionRegistry with available actions.
+     * Automatically registers core actions and discovers external plugins.
+     */
+    private initializeActionRegistry(): void {
+        this.logInfo("Initializing ActionRegistry...");
+        ActionRegistry.initialize();
+        this.logInfo("ActionRegistry initialized successfully.");
+    }
+
+    /**
+     * Sets up live reload functionality.
+     * Monitors file changes and restarts the pipeline when updates are detected.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    private setupLiveReload(
+        pipelineManager: PipelineManager,
+        liveReloadServer: LiveServer,
+    ): void {
+        this.logInfo("Enabling live reload functionality...");
+
+        new LiveWatcher((filePath) => {
+            this.logInfo(
+                `Detected change in: ${filePath}. Restarting pipeline...`,
+            );
+            pipelineManager.restartPipelineWithDelay(500);
+        });
+
+        pipelineManager.restartPipeline();
+        this.registerShutdownHandlers(pipelineManager, liveReloadServer);
+    }
+
+    /**
+     * Registers handlers for graceful shutdown signals.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    private registerShutdownHandlers(
+        pipelineManager: PipelineManager,
+        liveReloadServer: LiveServer,
+    ): void {
+        process.on("SIGINT", () =>
+            this.handleShutdown(pipelineManager, liveReloadServer),
+        );
+        process.on("SIGTERM", () =>
+            this.handleShutdown(pipelineManager, liveReloadServer),
+        );
+    }
+
+    /**
+     * Handles graceful shutdown of the pipeline and live reload server.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    private async handleShutdown(
+        pipelineManager: PipelineManager,
+        liveReloadServer: LiveServer,
+    ): Promise<void> {
+        this.logInfo("Shutdown signal received. Shutting down...");
+
+        try {
+            await pipelineManager.stopPipeline();
+            await liveReloadServer.shutdown();
+            this.logInfo("Shutdown completed successfully.");
+        } catch (error) {
+            this.logError("Error during shutdown.", error);
+        } finally {
+            process.exit(0);
+        }
+    }
+
+    /**
+     * Handles errors occurring during the execution of the Kist workflow.
+     *
+     * @param error - The error object to log and handle.
+     */
+    private handleError(error: unknown): void {
+        const errorMessage =
+            error instanceof Error ? error.message : String(error);
+        this.logError(`An error occurred: ${errorMessage}`, error);
+        process.exit(1);
+    }
+}

package/ts/live/LiveServer.ts

@@ -0,0 +1,311 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import express, { NextFunction, Request, Response } from "express";
+import rateLimit from "express-rate-limit";
+import { Server } from "http";
+import path from "path";
+import { WebSocket, WebSocketServer } from "ws";
+import { AbstractProcess } from "../core/abstract/AbstractProcess";
+import { ConfigStore } from "../core/config/ConfigStore";
+import { LiveOptionsInterface } from "../interface";
+import { OptionsInterface } from "../interface/OptionsInterface";
+
+// ============================================================================
+// 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.
+ */
+export class LiveServer extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * Express application
+     */
+    private app = express();
+
+    /**
+     * The underlying HTTP server used by the LiveServer.
+     * Handles incoming HTTP requests and serves static files.
+     */
+    private server: Server;
+
+    /**
+     * The WebSocket server responsible for managing WebSocket connections.
+     * Enables real-time communication with connected clients.
+     */
+    private wss: WebSocketServer;
+
+    /**
+     * A set of WebSocket clients currently connected to the server.
+     * Each client represents an active WebSocket connection.
+     */
+    private clients: Set<WebSocket> = new Set();
+
+    /**
+     * The port number on which the server is running.
+     * Defaults to 3000 if not specified in the configuration.
+     */
+    private port: number;
+
+    /**
+     * The root directory from which static files are served.
+     * Defaults to the "public" folder in the current working directory.
+     */
+    private root: string;
+
+    /**
+     * An array of paths to watch for changes.
+     * When a file within these paths changes, the server triggers live reload.
+     */
+    private watchPaths: string[];
+
+    /**
+     * 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: string[];
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Initializes the LiveServer.
+    //  * @param port - The port on which the server will listen.
+     */
+    constructor() {
+        super();
+
+        const configStore = ConfigStore.getInstance();
+
+        const liveReloadOptions: LiveOptionsInterface =
+            configStore.get<OptionsInterface["live"]>("options.live") || {};
+
+        // Extract and apply live reload options with defaults
+        this.port = liveReloadOptions.port || 3000;
+        this.root = path.resolve(
+            process.cwd(),
+            liveReloadOptions.root || "public",
+        );
+        this.watchPaths = (
+            liveReloadOptions.watchPaths || [
+                "src/**/*",
+                "config/**/*",
+                "pack.yaml",
+            ]
+        ).map((p: string) => path.resolve(process.cwd(), p));
+        this.ignoredPaths = (
+            liveReloadOptions.ignoredPaths || ["node_modules"]
+        ).map((p: string) => path.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 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.
+     */
+    private initializeServer(): void {
+        // 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 WebSocketServer({ server: this.server });
+    }
+
+    /** Logs initialization details for the LiveServer. */
+    private logInitializationDetails(): void {
+        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.
+     */
+    private setupRateLimiter(): void {
+        const limiter = rateLimit({
+            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.
+     */
+    private setupWebSocketHandlers(): void {
+        this.wss.on("connection", (ws: WebSocket) => {
+            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.
+     */
+    private setupMiddleware(): void {
+        // 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.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.
+     */
+    private injectLiveReloadScript(
+        req: Request,
+        res: Response,
+        next: NextFunction,
+    ): void {
+        if (req.url.endsWith(".html")) {
+            const sanitizedPath = path.join(
+                path.resolve(__dirname, "public"),
+                // Prevent directory traversal
+                path.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.
+     */
+    public reloadClients(): void {
+        this.logInfo("Reloading all connected clients...");
+
+        this.clients.forEach((client) => {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send("reload");
+            }
+        });
+    }
+
+    /**
+     * Gracefully shuts down the server and all WebSocket connections.
+     */
+    public async shutdown(): Promise<void> {
+        this.logInfo("Shutting down Live Reload Server...");
+
+        this.clients.forEach((client) => client.close());
+        this.wss.close();
+
+        await new Promise<void>((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.
+     */
+    private isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+        return typeof error === "object" && error !== null && "code" in error;
+    }
+}

package/ts/live/LiveWatcher.ts

@@ -0,0 +1,150 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import chokidar, { FSWatcher } from "chokidar";
+import { AbstractProcess } from "../core/abstract/AbstractProcess";
+import { ConfigStore } from "../core/config/ConfigStore";
+import { LiveOptionsInterface } from "../interface";
+import { OptionsInterface } from "../interface/OptionsInterface";
+
+// ============================================================================
+// 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.
+ */
+export class LiveWatcher extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * The chokidar file watcher instance.
+     */
+    private watcher: FSWatcher | null = null;
+
+    private pathsToWatch: string[];
+    private ignoredPaths: string[];
+    private onChange: (filePath: string) => void;
+
+    // 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: (filePath: string) => void,
+    ) {
+        super();
+
+        // Retrieve live reload configuration from ConfigStore
+        const liveReloadOptions: LiveOptionsInterface =
+            ConfigStore.getInstance().get<OptionsInterface["live"]>(
+                "options.live",
+            ) || {};
+
+        this.pathsToWatch = liveReloadOptions.watchPaths ?? [
+            "src/**/*",
+            "config/**/*",
+            "pack.yaml",
+        ];
+        this.ignoredPaths = liveReloadOptions.ignoredPaths ?? ["node_modules"];
+
+        this.onChange = onChange;
+
+        this.startWatching();
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Initializes and configures the chokidar watcher to monitor files and
+     * directories.
+     */
+    private 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.
+     */
+    public startWatching() {
+        if (this.watcher) {
+            this.logInfo("Watcher is already running.");
+            return;
+        }
+
+        this.logInfo("Starting file watcher...");
+        this.watcher = chokidar.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.
+     */
+    public async stopWatching() {
+        if (this.watcher) {
+            await 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.
+     */
+    public async restartWatcher() {
+        this.logInfo("Restarting file watcher...");
+        await this.stopWatching();
+        this.startWatching();
+    }
+}

package/ts/live/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// Live Reload Core - Entry Point
+// ============================================================================
+
+// Export core classes for live reload functionality
+
+// Manages server operations and live reload communication
+export { LiveServer } from "./LiveServer";
+
+// Watches for file changes and triggers reload actions
+export { LiveWatcher } from "./LiveWatcher";