kist 0.0.0 → 0.1.31

package/js/core/pipeline/ActionRegistry.js

@@ -0,0 +1,180 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionRegistry = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const CoreActions_1 = require("../../actions/CoreActions");
+const AbstractProcess_1 = require("../abstract/AbstractProcess");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * ActionRegistry is a singleton registry for step actions, mapping action
+ * names to their corresponding classes. This registry allows dynamic
+ * resolution of step actions within the pipeline and supports custom
+ * developer integrations.
+ */
+class ActionRegistry extends AbstractProcess_1.AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Constructs an ActionRegistry instance and automatically registers core
+     * actions. The constructor is private to enforce the singleton pattern.
+     */
+    constructor() {
+        // Initialize logging through AbstractProcess
+        super();
+        this.registry = new Map();
+        // Automatically register core actions
+        this.registerCoreActions();
+        this.discoverPlugins();
+        this.logInfo("ActionRegistry initialized.");
+    }
+    // Singleton Methods
+    // ========================================================================
+    /**
+     * Initializes the singleton instance of ActionRegistry.
+     * Should only be called once during application startup.
+     *
+     * @throws Error if the registry has already been initialized.
+     */
+    static initialize() {
+        if (ActionRegistry.instance) {
+            throw new Error("ActionRegistry has already been initialized.");
+        }
+        ActionRegistry.instance = new ActionRegistry();
+    }
+    /**
+     * Retrieves the singleton instance of ActionRegistry, initializing it if
+     * necessary.
+     *
+     * @returns The ActionRegistry instance.
+     */
+    static getInstance() {
+        if (!ActionRegistry.instance) {
+            ActionRegistry.instance = new ActionRegistry();
+        }
+        return ActionRegistry.instance;
+    }
+    /**
+     * Resets the singleton instance of ActionRegistry.
+     * This is useful for testing or resetting the registry state during
+     * runtime.
+     */
+    static resetInstance() {
+        ActionRegistry.instance = null;
+    }
+    // Instance Methods
+    // ========================================================================
+    /**
+     * Registers a new action in the registry.
+     *
+     * @param actionClass - The class implementing `ActionInterface`.
+     * @throws Error if the action name is already registered or missing.
+     */
+    registerAction(actionClass) {
+        const actionInstance = new actionClass();
+        const name = actionInstance.name;
+        if (!name || typeof name !== "string") {
+            throw new Error(`[ActionRegistry] Action class must have a valid 'name' property.`);
+        }
+        if (this.registry.has(name)) {
+            throw new Error(`[ActionRegistry] Action "${name}" is already registered.`);
+        }
+        this.registry.set(name, actionClass);
+        this.logInfo(`Action "${name}" registered successfully.`);
+    }
+    /**
+     * Retrieves a step action class from the registry.
+     * This method looks up an action by name and returns the corresponding
+     * class that implements the ActionInterface.
+     *
+     * @param name - The name of the action to retrieve.
+     * @returns The action class constructor if found, or undefined if no such
+     *  action is registered.
+     */
+    getAction(name) {
+        // Validate the input name
+        if (!name || typeof name !== "string") {
+            this.logWarn(`Invalid action name requested: "${name}".`);
+            return undefined;
+        }
+        // Retrieve the action from the registry
+        const action = this.registry.get(name);
+        // Log a warning if the action is not found
+        if (!action) {
+            this.logWarn(`Action "${name}" not found in the registry.`);
+        }
+        else {
+            this.logDebug(`Retrieved action "${name}" from the registry.`);
+        }
+        return action;
+    }
+    /**
+     * Lists all registered step actions.
+     * Provides a utility to view currently registered actions, useful for
+     * debugging and validation.
+     *
+     * @returns An array of registered action names.
+     */
+    listRegisteredActions() {
+        this.logDebug("Listing all registered actions.");
+        return Array.from(this.registry.keys());
+    }
+    /**
+     * Pre-registers core actions that are included with the pipeline by
+     * default. Developers can extend this by registering additional custom
+     * actions as needed.
+     */
+    registerCoreActions() {
+        Object.values(CoreActions_1.coreActions).forEach((actionClass) => {
+            this.registerAction(actionClass);
+        });
+        this.logInfo("Core actions registered successfully.");
+    }
+    discoverPlugins() {
+        this.logInfo("Discovering external plugins...");
+        const nodeModulesPath = (0, path_1.join)(process.cwd(), "node_modules");
+        const pluginPrefix = "@kist/plugin-";
+        try {
+            const directories = (0, fs_1.readdirSync)(nodeModulesPath, {
+                withFileTypes: true,
+            });
+            for (const dir of directories) {
+                if (dir.isDirectory() && dir.name.startsWith(pluginPrefix)) {
+                    const pluginPath = (0, path_1.join)(nodeModulesPath, dir.name);
+                    const plugin = require(pluginPath).default;
+                    if (plugin &&
+                        typeof plugin.registerActions === "function") {
+                        const actions = plugin.registerActions();
+                        for (const [name, actionClass] of Object.entries(actions)) {
+                            this.registerAction(actionClass);
+                        }
+                    }
+                }
+            }
+            this.logInfo("Plugins loaded successfully.");
+        }
+        catch (error) {
+            this.logError("Failed to discover plugins.", error);
+        }
+    }
+    /**
+     * Clears all registered actions in the registry.
+     * Useful for testing or resetting the pipeline.
+     */
+    clearRegistry() {
+        this.registry.clear();
+        this.logInfo("Registry cleared.");
+    }
+}
+exports.ActionRegistry = ActionRegistry;
+// Parameters
+// ========================================================================
+/**
+ * Singleton instance
+ */
+ActionRegistry.instance = null;

package/js/core/pipeline/Pipeline.d.ts

@@ -0,0 +1,42 @@
+import { ConfigInterface } from "../../interface/ConfigInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * Represents the pipeline of stages to be executed.
+ * This class manages the execution flow of stages, including parallel
+ * execution, dependency handling, and applying global options for consistent
+ * pipeline behavior.
+ */
+export declare class Pipeline extends AbstractProcess {
+    private config;
+    /**
+     * List of stages to be executed in the pipeline.
+     */
+    private stages;
+    /**
+     * Global options that apply across the entire pipeline.
+     */
+    private options?;
+    /**
+     * Constructs a new Pipeline instance with the given configuration.
+     * Initializes stages and applies global options for execution control.
+     *
+     * @param config - The configuration object defining the stages, steps,
+     * and global options for the pipeline.
+     */
+    constructor(config: ConfigInterface);
+    /**
+     * Runs the pipeline, executing stages based on their dependencies.
+     * Stages are run in parallel by default, but their execution respects
+     * defined dependencies. Applies global options for logging, error
+     * handling, and execution control.
+     */
+    run(): Promise<void>;
+    /**
+     * Runs the stage promises with concurrency control based on global
+     * options. Limits the number of parallel running stages if
+     * maxConcurrentStages is set in global options.
+     * @param stagePromises - An array of promises representing stage
+     * executions.
+     */
+    private runWithConcurrencyControl;
+}

package/js/core/pipeline/Pipeline.js

@@ -0,0 +1,107 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pipeline = void 0;
+const AbstractProcess_1 = require("../abstract/AbstractProcess");
+const Stage_1 = require("./Stage");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * Represents the pipeline of stages to be executed.
+ * This class manages the execution flow of stages, including parallel
+ * execution, dependency handling, and applying global options for consistent
+ * pipeline behavior.
+ */
+class Pipeline extends AbstractProcess_1.AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Constructs a new Pipeline instance with the given configuration.
+     * Initializes stages and applies global options for execution control.
+     *
+     * @param config - The configuration object defining the stages, steps,
+     * and global options for the pipeline.
+     */
+    constructor(config) {
+        super();
+        this.config = config;
+        this.stages = config.stages.map((stage) => new Stage_1.Stage(stage));
+        this.options = config.options;
+        this.logInfo("Pipeline instance created.");
+    }
+    // Methods
+    // ========================================================================
+    /**
+     * Runs the pipeline, executing stages based on their dependencies.
+     * Stages are run in parallel by default, but their execution respects
+     * defined dependencies. Applies global options for logging, error
+     * handling, and execution control.
+     */
+    run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            this.logInfo("Starting pipeline execution...");
+            // Track stages that have been completed
+            const completedStages = new Set();
+            // Run stages with dependency management and parallel execution control
+            try {
+                this.logDebug("Pipeline execution started with debug logging.");
+                // Execute all stages with concurrency control
+                const stagePromises = this.stages.map((stage) => stage.execute(completedStages));
+                yield this.runWithConcurrencyControl(stagePromises);
+                this.logInfo("Pipeline execution completed successfully.");
+            }
+            catch (error) {
+                this.logError("Pipeline execution failed:", error);
+                // Halt pipeline if configured to do so on failure
+                if (((_a = this.options) === null || _a === void 0 ? void 0 : _a.haltOnFailure) !== false) {
+                    this.logError("Halting pipeline due to failure.");
+                    process.exit(1);
+                }
+                else {
+                    this.logWarn("Continuing pipeline execution despite errors.");
+                }
+            }
+        });
+    }
+    /**
+     * Runs the stage promises with concurrency control based on global
+     * options. Limits the number of parallel running stages if
+     * maxConcurrentStages is set in global options.
+     * @param stagePromises - An array of promises representing stage
+     * executions.
+     */
+    runWithConcurrencyControl(stagePromises) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const maxConcurrentStages = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.maxConcurrentStages) || stagePromises.length;
+            // Process stages with a concurrency limit
+            const executingStages = new Set();
+            for (const stagePromise of stagePromises) {
+                executingStages.add(stagePromise);
+                // Ensure stages are removed from the set once complete
+                stagePromise.finally(() => executingStages.delete(stagePromise));
+                // Enforce concurrency limit
+                if (executingStages.size >= maxConcurrentStages) {
+                    // Wait until at least one stage completes
+                    yield Promise.race(executingStages);
+                }
+            }
+            // Wait for all remaining stages to complete
+            yield Promise.all(executingStages);
+        });
+    }
+}
+exports.Pipeline = Pipeline;

package/js/core/pipeline/PipelineManager.d.ts

@@ -0,0 +1,55 @@
+import { LiveServer } from "../../live/LiveServer";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * Manages the lifecycle of the pipeline process and integrates with the
+ * LiveServer for client notifications upon pipeline events.
+ */
+export declare class PipelineManager extends AbstractProcess {
+    private liveServer?;
+    /**
+     * The current instance of the pipeline process.
+     */
+    private pipelineProcess;
+    /**
+     * Flag to prevent overlapping restarts.
+     */
+    private isRestarting;
+    /**
+     * Initializes the PipelineManager with a LiveServer instance.
+     *
+     * @param liveServer - The LiveServer instance to notify when the
+     * pipeline restarts.
+     */
+    constructor(liveServer?: LiveServer | undefined);
+    /**
+     * Runs the pipeline using the configuration from the `ConfigStore`.
+     * This method executes the pipeline stages directly, bypassing the CLI.
+     */
+    runPipeline(): Promise<void>;
+    /**
+     * Restarts the pipeline process, stopping any currently running process.
+     * Notifies connected clients via the LiveServer after restarting.
+     */
+    restartPipeline(): void;
+    /**
+     * Attaches event listeners to the pipeline process for logging and
+     * notification purposes.
+     */
+    private attachProcessListeners;
+    /**
+     * Stops the currently running pipeline process, if any.
+     * Gracefully kills the process and handles cleanup.
+     */
+    stopPipeline(): void;
+    /**
+     * Checks if the pipeline process is currently running.
+     * @returns True if the pipeline process is running, false otherwise.
+     */
+    isPipelineRunning(): boolean;
+    /**
+     * Restarts the pipeline with a delay, useful for throttling restarts when
+     * changes occur rapidly.
+     * @param delay - The delay in milliseconds before restarting the pipeline.
+     */
+    restartPipelineWithDelay(delay?: number): void;
+}

package/js/core/pipeline/PipelineManager.js

@@ -0,0 +1,164 @@
+"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.PipelineManager = void 0;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const AbstractProcess_1 = require("../abstract/AbstractProcess");
+const ConfigStore_1 = require("../config/ConfigStore");
+const Pipeline_1 = require("./Pipeline");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * Manages the lifecycle of the pipeline process and integrates with the
+ * LiveServer for client notifications upon pipeline events.
+ */
+class PipelineManager extends AbstractProcess_1.AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Initializes the PipelineManager with a LiveServer instance.
+     *
+     * @param liveServer - The LiveServer instance to notify when the
+     * pipeline restarts.
+     */
+    constructor(liveServer) {
+        super();
+        this.liveServer = liveServer;
+        // Parameters
+        // ========================================================================
+        /**
+         * The current instance of the pipeline process.
+         */
+        this.pipelineProcess = null;
+        /**
+         * Flag to prevent overlapping restarts.
+         */
+        this.isRestarting = false;
+        this.logInfo("PipelineManager initialized.");
+    }
+    // Methods
+    // ========================================================================
+    /**
+     * Runs the pipeline using the configuration from the `ConfigStore`.
+     * This method executes the pipeline stages directly, bypassing the CLI.
+     */
+    runPipeline() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const config = ConfigStore_1.ConfigStore.getInstance().getConfig();
+            if (!config.stages || !Array.isArray(config.stages)) {
+                throw new Error("Invalid configuration: 'stages' must be an array.");
+            }
+            this.logInfo("Initializing pipeline...");
+            const pipeline = new Pipeline_1.Pipeline(config);
+            try {
+                yield pipeline.run();
+                this.logInfo("Pipeline execution finished successfully.");
+                (_a = this.liveServer) === null || _a === void 0 ? void 0 : _a.reloadClients();
+            }
+            catch (error) {
+                this.logError("Error during pipeline execution.", error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Restarts the pipeline process, stopping any currently running process.
+     * Notifies connected clients via the LiveServer after restarting.
+     */
+    restartPipeline() {
+        if (this.isRestarting) {
+            this.logWarn("Pipeline restart already in progress. Skipping...");
+            return;
+        }
+        this.isRestarting = true;
+        if (this.pipelineProcess) {
+            this.logInfo("Stopping current pipeline process...");
+            this.stopPipeline();
+        }
+        this.logInfo("Starting pipeline...");
+        const scriptPath = path_1.default.resolve(process.cwd(), "dist/js/cli.js");
+        this.pipelineProcess = (0, child_process_1.spawn)("node", [scriptPath], {
+            stdio: "inherit",
+        });
+        this.attachProcessListeners();
+        this.isRestarting = false;
+    }
+    /**
+     * Attaches event listeners to the pipeline process for logging and
+     * notification purposes.
+     */
+    attachProcessListeners() {
+        if (!this.pipelineProcess)
+            return;
+        this.pipelineProcess.on("close", (code) => {
+            var _a;
+            if (code !== 0) {
+                this.logError(`Pipeline process exited with code ${code}`);
+            }
+            else {
+                this.logInfo("Pipeline process exited successfully.");
+            }
+            (_a = this.liveServer) === null || _a === void 0 ? void 0 : _a.reloadClients();
+        });
+        this.pipelineProcess.on("error", (error) => {
+            this.logError("Error starting pipeline process.", error);
+        });
+        this.pipelineProcess.on("exit", (code, signal) => {
+            if (signal) {
+                this.logWarn(`Pipeline process was terminated with signal: ${signal}`);
+            }
+            else {
+                this.logInfo(`Pipeline process exited with code: ${code}`);
+            }
+        });
+    }
+    /**
+     * Stops the currently running pipeline process, if any.
+     * Gracefully kills the process and handles cleanup.
+     */
+    stopPipeline() {
+        if (this.pipelineProcess) {
+            this.logInfo("Stopping pipeline process...");
+            this.pipelineProcess.kill("SIGTERM");
+            this.pipelineProcess = null;
+            this.logInfo("Pipeline process stopped.");
+        }
+        else {
+            this.logWarn("No pipeline process is currently running.");
+        }
+    }
+    /**
+     * Checks if the pipeline process is currently running.
+     * @returns True if the pipeline process is running, false otherwise.
+     */
+    isPipelineRunning() {
+        return this.pipelineProcess !== null && !this.pipelineProcess.killed;
+    }
+    /**
+     * Restarts the pipeline with a delay, useful for throttling restarts when
+     * changes occur rapidly.
+     * @param delay - The delay in milliseconds before restarting the pipeline.
+     */
+    restartPipelineWithDelay(delay = 1000) {
+        this.logInfo(`Delaying pipeline restart by ${delay} milliseconds...`);
+        setTimeout(() => this.restartPipeline(), delay);
+    }
+}
+exports.PipelineManager = PipelineManager;

package/js/core/pipeline/Stage.d.ts

@@ -0,0 +1,45 @@
+import { StageInterface } from "../../interface/StageInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * Represents a stage in the pipeline, encapsulating its execution logic and
+ * dependencies. Each stage consists of multiple steps that are executed
+ * consecutively, and stages can have dependencies on other stages which are
+ * managed before execution.
+ */
+export declare class Stage extends AbstractProcess {
+    private name;
+    private steps;
+    private dependsOn?;
+    /**
+     * Constructs a Stage instance with the given stage definition.
+     * @param stage - The stage definition containing name, steps, and
+     * dependencies.
+     */
+    constructor(stage: StageInterface);
+    /**
+     * Executes the stage by running its steps consecutively.
+     * Manages dependencies by waiting for dependent stages to complete
+     * before execution.
+     * @param completedStages - A set of completed stage names used for
+     * dependency tracking.
+     * @throws Error if any step within the stage fails.
+     */
+    execute(completedStages: Set<string>): Promise<void>;
+    /**
+     * Resolves dependencies by ensuring all required stages have completed.
+     * @param completedStages - A set of completed stage names used for
+     * dependency tracking.
+     * @returns A promise that resolves once all dependencies are met.
+     */
+    private resolveDependencies;
+    /**
+     * Waits for a specified stage to complete by monitoring the completed
+     * stages set.
+     * @param stageName - The name of the stage to wait for.
+     * @param completedStages - A set of completed stage names used for
+     * dependency tracking.
+     * @returns A promise that resolves when the specified stage is marked
+     * as completed.
+     */
+    private waitForStageCompletion;
+}