kist 0.0.0 → 0.1.30

package/ts/core/pipeline/ActionRegistry.ts

@@ -0,0 +1,216 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { readdirSync } from "fs";
+import { join } from "path";
+import { coreActions } from "../../actions/CoreActions";
+import { ActionInterface } from "../../interface/ActionInterface";
+import { ActionPlugin } from "../../interface/ActionPlugin";
+import { AbstractProcess } from "../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.
+ */
+export class ActionRegistry extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * Singleton instance
+     */
+    private static instance: ActionRegistry | null = null;
+
+    /**
+     * Map to store registered actions
+     */
+    private registry: Map<string, new () => ActionInterface>;
+
+    // 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.
+     */
+    public static initialize(): void {
+        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.
+     */
+    public static getInstance(): ActionRegistry {
+        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.
+     */
+    public static resetInstance(): void {
+        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.
+     */
+    public registerAction(actionClass: new () => ActionInterface): void {
+        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.
+     */
+    public getAction(name: string): (new () => ActionInterface) | undefined {
+        // 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.
+     */
+    public listRegisteredActions(): string[] {
+        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.
+     */
+    private registerCoreActions(): void {
+        Object.values(coreActions).forEach((actionClass) => {
+            this.registerAction(actionClass);
+        });
+        this.logInfo("Core actions registered successfully.");
+    }
+
+    private discoverPlugins(): void {
+        this.logInfo("Discovering external plugins...");
+
+        const nodeModulesPath = join(process.cwd(), "node_modules");
+        const pluginPrefix = "@kist/plugin-";
+
+        try {
+            const directories = readdirSync(nodeModulesPath, {
+                withFileTypes: true,
+            });
+
+            for (const dir of directories) {
+                if (dir.isDirectory() && dir.name.startsWith(pluginPrefix)) {
+                    const pluginPath = join(nodeModulesPath, dir.name);
+                    const plugin: ActionPlugin = 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.
+     */
+    public clearRegistry(): void {
+        this.registry.clear();
+        this.logInfo("Registry cleared.");
+    }
+}

package/ts/core/pipeline/Pipeline.ts

@@ -0,0 +1,121 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ConfigInterface } from "../../interface/ConfigInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+import { Stage } from "./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.
+ */
+export class Pipeline extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * List of stages to be executed in the pipeline.
+     */
+    private stages: Stage[];
+
+    /**
+     * Global options that apply across the entire pipeline.
+     */
+    private options?: ConfigInterface["options"];
+
+    // 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(private config: ConfigInterface) {
+        super();
+        this.stages = config.stages.map((stage) => new 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.
+     */
+    async run(): Promise<void> {
+        this.logInfo("Starting pipeline execution...");
+
+        // Track stages that have been completed
+        const completedStages = new Set<string>();
+
+        // 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),
+            );
+            await 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 (this.options?.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.
+     */
+    private async runWithConcurrencyControl(
+        stagePromises: Promise<void>[],
+    ): Promise<void> {
+        const maxConcurrentStages =
+            this.options?.maxConcurrentStages || stagePromises.length;
+
+        // Process stages with a concurrency limit
+        const executingStages = new Set<Promise<void>>();
+
+        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 as number)) {
+                // Wait until at least one stage completes
+                await Promise.race(executingStages);
+            }
+        }
+
+        // Wait for all remaining stages to complete
+        await Promise.all(executingStages);
+    }
+}

package/ts/core/pipeline/PipelineManager.ts

@@ -0,0 +1,170 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ChildProcess, spawn } from "child_process";
+import path from "path";
+import { LiveServer } from "../../live/LiveServer";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+import { ConfigStore } from "../config/ConfigStore";
+import { Pipeline } from "./Pipeline";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * Manages the lifecycle of the pipeline process and integrates with the
+ * LiveServer for client notifications upon pipeline events.
+ */
+export class PipelineManager extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * The current instance of the pipeline process.
+     */
+    private pipelineProcess: ChildProcess | null = null;
+
+    /**
+     * Flag to prevent overlapping restarts.
+     */
+    private isRestarting: boolean = false;
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Initializes the PipelineManager with a LiveServer instance.
+     *
+     * @param liveServer - The LiveServer instance to notify when the
+     * pipeline restarts.
+     */
+    constructor(private liveServer?: LiveServer) {
+        super();
+        this.logInfo("PipelineManager initialized.");
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Runs the pipeline using the configuration from the `ConfigStore`.
+     * This method executes the pipeline stages directly, bypassing the CLI.
+     */
+    public async runPipeline(): Promise<void> {
+        const config = 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(config);
+
+        try {
+            await pipeline.run();
+
+            this.logInfo("Pipeline execution finished successfully.");
+            this.liveServer?.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.
+     */
+    public restartPipeline(): void {
+        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.resolve(process.cwd(), "dist/js/cli.js");
+
+        this.pipelineProcess = spawn("node", [scriptPath], {
+            stdio: "inherit",
+        });
+
+        this.attachProcessListeners();
+
+        this.isRestarting = false;
+    }
+
+    /**
+     * Attaches event listeners to the pipeline process for logging and
+     * notification purposes.
+     */
+    private attachProcessListeners(): void {
+        if (!this.pipelineProcess) return;
+
+        this.pipelineProcess.on("close", (code) => {
+            if (code !== 0) {
+                this.logError(`Pipeline process exited with code ${code}`);
+            } else {
+                this.logInfo("Pipeline process exited successfully.");
+            }
+            this.liveServer?.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.
+     */
+    public stopPipeline(): void {
+        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.
+     */
+    public isPipelineRunning(): boolean {
+        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.
+     */
+    public restartPipelineWithDelay(delay: number = 1000): void {
+        this.logInfo(`Delaying pipeline restart by ${delay} milliseconds...`);
+        setTimeout(() => this.restartPipeline(), delay);
+    }
+}

package/ts/core/pipeline/Stage.ts

@@ -0,0 +1,131 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { StageInterface } from "../../interface/StageInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+import { Step } from "./Step";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * 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 class Stage extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    private name: string;
+    private steps: Step[];
+    private dependsOn?: string[];
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Constructs a Stage instance with the given stage definition.
+     * @param stage - The stage definition containing name, steps, and
+     * dependencies.
+     */
+    constructor(stage: StageInterface) {
+        super(); // Initialize logging
+        this.name = stage.name;
+        this.steps = stage.steps.map((step) => new Step(step));
+        this.dependsOn = stage.dependsOn;
+
+        this.logInfo(
+            `Stage "${this.name}" initialized with ${this.steps.length} steps.`,
+        );
+    }
+
+    // Methods
+    // ========================================================================
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * 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.
+     */
+    async execute(completedStages: Set<string>): Promise<void> {
+        // Handle dependencies before executing the stage
+        if (this.dependsOn) {
+            await this.resolveDependencies(completedStages);
+        }
+
+        this.logInfo(`Executing stage: ${this.name}`);
+
+        // Execute all steps within the stage consecutively
+        try {
+            for (const step of this.steps) {
+                await step.execute();
+            }
+            this.logInfo(`Stage "${this.name}" completed successfully.`);
+            completedStages.add(this.name);
+        } catch (error) {
+            this.logError(
+                `Error executing stage "${this.name}": ${error}`,
+                error,
+            );
+            // Propagate the error to halt pipeline or manage based on
+            // global settings
+            throw error;
+        }
+    }
+
+    /**
+     * 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 async resolveDependencies(
+        completedStages: Set<string>,
+    ): Promise<void> {
+        if (!this.dependsOn) return;
+
+        this.logInfo(
+            `Stage "${this.name}" is waiting for
+            dependencies:${this.dependsOn.join(", ")}`,
+        );
+        await Promise.all(
+            this.dependsOn.map((dep) =>
+                this.waitForStageCompletion(dep, completedStages),
+            ),
+        );
+        this.logInfo(`All dependencies resolved for stage: "${this.name}"`);
+    }
+
+    /**
+     * 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 async waitForStageCompletion(
+        stageName: string,
+        completedStages: Set<string>,
+    ): Promise<void> {
+        while (!completedStages.has(stageName)) {
+            await new Promise((resolve) =>
+                setTimeout(
+                    resolve,
+                    100, // Polling interval to check completion status
+                ),
+            );
+        }
+    }
+}