kist 0.0.0 → 0.1.31

package/ts/core/config/ConfigStore copy.ts

@@ -0,0 +1,201 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ConfigInterface } from "../../interface/ConfigInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+import { defaultConfig } from "./defaultConfig";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * ConfigStore is a singleton that loads and manages the application's
+ * configuration.
+ * It prioritizes CLI arguments over configuration file values.
+ */
+export class ConfigStore extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * Singleton instance of the ConfigStore.
+     */
+    private static instance: ConfigStore | null = null;
+
+    /**
+     * The current configuration stored in the ConfigStore.
+     */
+    private config: ConfigInterface;
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Private constructor to enforce the singleton pattern.
+     * Initializes the store with the default configuration.
+     */
+    private constructor() {
+        super();
+        this.config = defaultConfig;
+        this.logDebug("ConfigStore initialized with default configuration.");
+    }
+
+    // Static Methods
+    // ========================================================================
+
+    /**
+     * Retrieves the singleton instance of ConfigStore, initializing it if
+     * necessary.
+     * @returns The singleton instance of ConfigStore.
+     */
+    public static getInstance(): ConfigStore {
+        if (!ConfigStore.instance) {
+            ConfigStore.instance = new ConfigStore();
+        }
+        return ConfigStore.instance;
+    }
+
+    // Instance Methods
+    // ========================================================================
+
+    /**
+     * Retrieves a value from the configuration by key.
+     * Supports nested keys using dot notation (e.g., "options.logLevel").
+     *
+     * @param key - The key of the configuration to retrieve.
+     * @returns The configuration value or undefined if not found.
+     */
+    public get<T>(key: string): T | undefined {
+        const keys = key.split(".");
+        let current: any = this.config;
+
+        for (const k of keys) {
+            if (current[k] === undefined) {
+                return undefined;
+            }
+            current = current[k];
+        }
+
+        this.logDebug(
+            `Configuration key "${key}" retrieved with value: ${JSON.stringify(current)}`,
+        );
+        return current as T;
+    }
+
+    /**
+     * Sets a value in the configuration by key.
+     * Supports nested keys using dot notation (e.g., "options.logLevel").
+     *
+     * @param key - The key of the configuration to set.
+     * @param value - The value to set.
+     */
+    public set(key: string, value: unknown): void {
+        const keys = key.split(".");
+        let current: any = this.config;
+
+        for (let i = 0; i < keys.length - 1; i++) {
+            const k = keys[i];
+            if (!current[k] || typeof current[k] !== "object") {
+                current[k] = {};
+            }
+            current = current[k];
+        }
+
+        current[keys[keys.length - 1]] = value;
+        this.logDebug(
+            `Set configuration key "${key}" to: ${JSON.stringify(value)}`,
+        );
+    }
+
+    /**
+     * Merges the provided configuration into the existing configuration.
+     * Uses a deep merge strategy to combine objects and overwrite primitives.
+     *
+     * @param newConfig - The new configuration to merge.
+     */
+    public merge(newConfig: Partial<ConfigInterface>): void {
+        this.config = this.deepMerge(this.config, newConfig);
+        this.logDebug("Configuration successfully merged.");
+    }
+
+    /**
+     * Retrieves the current configuration.
+     *
+     * @returns The current configuration object.
+     */
+    public getConfig(): ConfigInterface {
+        return this.config;
+    }
+
+    /**
+     * Prints the current configuration to the console in a readable format.
+     */
+    public print(): void {
+        console.log("Current Configuration:");
+        console.log(JSON.stringify(this.config, null, 2));
+    }
+
+    /**
+     * Deeply merges two objects.
+     *
+     * @param target - The target object to merge into.
+     * @param source - The source object to merge from.
+     * @returns The merged object.
+     */
+    // private deepMerge(target: any, source: any): any {
+    //     if (typeof target !== "object" || target === null) {
+    //         return source;
+    //     }
+
+    //     for (const key of Object.keys(source)) {
+    //         if (
+    //             source[key] &&
+    //             typeof source[key] === "object" &&
+    //             !Array.isArray(source[key])
+    //         ) {
+    //             if (!target[key] || typeof target[key] !== "object") {
+    //                 target[key] = {};
+    //             }
+    //             target[key] = this.deepMerge(target[key], source[key]);
+    //         } else {
+    //             target[key] = source[key];
+    //         }
+    //     }
+
+    //     return target;
+    // }
+    private deepMerge(target: any, source: any): any {
+        if (typeof target !== "object" || target === null) {
+            return source;
+        }
+
+        for (const key of Object.keys(source)) {
+            // Prevent prototype pollution
+            if (
+                key === "__proto__" ||
+                key === "constructor" ||
+                key === "prototype"
+            ) {
+                this.logWarn(`Skipping potentially unsafe key: "${key}"`);
+                continue;
+            }
+
+            if (
+                source[key] &&
+                typeof source[key] === "object" &&
+                !Array.isArray(source[key])
+            ) {
+                if (!target[key] || typeof target[key] !== "object") {
+                    target[key] = {};
+                }
+                target[key] = this.deepMerge(target[key], source[key]);
+            } else {
+                target[key] = source[key];
+            }
+        }
+
+        return target;
+    }
+}

package/ts/core/config/ConfigStore.ts

@@ -0,0 +1,157 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ConfigInterface } from "../../interface/ConfigInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+import { defaultConfig } from "./defaultConfig";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * ConfigStore is a singleton that loads and manages the application's configuration.
+ * It prioritizes CLI arguments over configuration file values.
+ */
+export class ConfigStore extends AbstractProcess {
+    // Singleton instance
+    private static instance: ConfigStore | null = null;
+
+    // The current configuration stored in the ConfigStore.
+    private config: ConfigInterface;
+
+    // Constructor (Private to enforce Singleton Pattern)
+    private constructor() {
+        super();
+        this.config = defaultConfig;
+        this.logDebug("ConfigStore initialized with default configuration.");
+    }
+
+    /**
+     * Retrieves the singleton instance of ConfigStore.
+     * @returns The singleton instance of ConfigStore.
+     */
+    public static getInstance(): ConfigStore {
+        if (!ConfigStore.instance) {
+            ConfigStore.instance = new ConfigStore();
+        }
+        return ConfigStore.instance;
+    }
+
+    /**
+     * Retrieves a value from the configuration using dot notation.
+     *
+     * @param key - The key of the configuration to retrieve.
+     * @returns The configuration value or undefined if not found.
+     */
+    public get<T>(key: string): T | undefined {
+        const keys = key.split(".");
+        let current: any = this.config;
+
+        for (const k of keys) {
+            if (current[k] === undefined) {
+                return undefined;
+            }
+            current = current[k];
+        }
+
+        this.logDebug(`Configuration key "${key}" retrieved.`);
+        return current as T;
+    }
+
+    /**
+     * Sets a value in the configuration using dot notation.
+     *
+     * @param key - The key of the configuration to set.
+     * @param value - The value to set.
+     */
+    public set(key: string, value: unknown): void {
+        const keys = key.split(".");
+        let current: any = this.config;
+
+        for (let i = 0; i < keys.length - 1; i++) {
+            const k = keys[i];
+
+            // Prevent prototype pollution by blocking reserved keywords
+            if (["__proto__", "constructor", "prototype"].includes(k)) {
+                this.logWarn(`Attempted prototype pollution detected: "${k}"`);
+                return;
+            }
+
+            // Ensure property exists and is an object
+            if (!Object.prototype.hasOwnProperty.call(current, k) || typeof current[k] !== "object") {
+                current[k] = Object.create(null); // Use a null prototype object
+            }
+            current = current[k];
+        }
+
+        const finalKey = keys[keys.length - 1];
+
+        // Prevent prototype pollution at the final assignment
+        if (["__proto__", "constructor", "prototype"].includes(finalKey)) {
+            this.logWarn(`Attempted prototype pollution detected: "${finalKey}"`);
+            return;
+        }
+
+        current[finalKey] = value;
+        this.logDebug(`Set configuration key "${key}" to: ${JSON.stringify(value)}`);
+    }
+
+    /**
+     * Merges the provided configuration into the existing configuration using deep merge.
+     *
+     * @param newConfig - The new configuration to merge.
+     */
+    public merge(newConfig: Partial<ConfigInterface>): void {
+        this.config = this.deepMerge(this.config, newConfig);
+        this.logDebug("Configuration successfully merged.");
+    }
+
+    /**
+     * Retrieves the current configuration object.
+     * @returns The current configuration.
+     */
+    public getConfig(): ConfigInterface {
+        return this.config;
+    }
+
+    /**
+     * Prints the current configuration to the console.
+     */
+    public print(): void {
+        console.log("Current Configuration:", JSON.stringify(this.config, null, 2));
+    }
+
+    /**
+     * Deeply merges two objects, preventing prototype pollution.
+     *
+     * @param target - The target object.
+     * @param source - The source object.
+     * @returns The merged object.
+     */
+    private deepMerge(target: any, source: any): any {
+        if (typeof target !== "object" || target === null) {
+            return source;
+        }
+
+        for (const key of Object.keys(source)) {
+            // Prevent prototype pollution
+            if (["__proto__", "constructor", "prototype"].includes(key)) {
+                this.logWarn(`Skipping unsafe key during merge: "${key}"`);
+                continue;
+            }
+
+            if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key])) {
+                if (!Object.prototype.hasOwnProperty.call(target, key) || typeof target[key] !== "object") {
+                    target[key] = Object.create(null);
+                }
+                target[key] = this.deepMerge(target[key], source[key]);
+            } else {
+                target[key] = source[key];
+            }
+        }
+
+        return target;
+    }
+}

package/ts/core/config/defaultConfig.ts

@@ -0,0 +1,154 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ConfigInterface } from "../../interface/ConfigInterface";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Default configuration for the kist pipeline.
+ */
+export const defaultConfig: ConfigInterface = {
+    metadata: {
+        /**
+         * The name of the pipeline for identification and reporting.
+         */
+        name: "kist pipeline",
+
+        /**
+         * Semantic version of the pipeline configuration for tracking changes.
+         */
+        version: "1.0.0",
+
+        /**
+         * Detailed description outlining the purpose of the pipeline.
+         */
+        description: "A generic pipeline configuration for kist.",
+
+        /**
+         * The author or owner of the pipeline configuration.
+         */
+        author: "Anonymous",
+
+        /**
+         * Arbitrary key-value pairs to describe the pipeline.
+         */
+        tags: {
+            category: "generic",
+            environment: "development",
+        },
+
+        /**
+         * Timestamp indicating when the configuration was created or last updated.
+         * Automatically set to the current date/time.
+         */
+        timestamp: new Date().toISOString(),
+
+        /**
+         * License under which the pipeline configuration is shared or used.
+         */
+        license: "MIT",
+
+        /**
+         * URL pointing to documentation or additional resources for the pipeline.
+         */
+        documentation: "https://example.com/documentation",
+
+        /**
+         * Contact information for questions or support.
+         */
+        contact: "support@example.com",
+
+        /**
+         * Dependencies or related systems required by the pipeline configuration.
+         */
+        dependencies: ["Node.js >=14.0", "Docker >=20.10"],
+
+        /**
+         * Environments where the pipeline is intended to run.
+         */
+        environments: ["local", "CI/CD", "staging", "production"],
+    },
+
+    options: {
+        /**
+         * Configuration settings for live reload functionality.
+         */
+        live: {
+            /**
+             * Indicates whether live reload is enabled.
+             */
+            enabled: false,
+
+            /**
+             * Port on which the live reload server listens.
+             */
+            port: 3000,
+
+            /**
+             * Root directory for serving static files.
+             */
+            root: "public",
+
+            /**
+             * Paths to watch for changes.
+             */
+            watchPaths: ["src/**/*", "config/**/*", "kist.yaml"],
+
+            /**
+             * Paths or patterns to ignore while watching.
+             */
+            ignoredPaths: ["node_modules/*"],
+        },
+
+        /**
+         * Configuration options for pipeline execution.
+         */
+        pipeline: {
+            /**
+             * Default timeout in milliseconds for each step in the pipeline.
+             */
+            stepTimeout: 30000,
+
+            /**
+             * Whether to halt the pipeline if a step fails.
+             */
+            haltOnFailure: true,
+
+            /**
+             * Maximum number of concurrent stages allowed to run in parallel.
+             * Set to 0 for no limit.
+             */
+            maxConcurrentStages: 0,
+
+            /**
+             * Retry strategy for steps that fail.
+             */
+            retryStrategy: {
+                /**
+                 * Number of retry attempts before marking a step as failed.
+                 */
+                retries: 3,
+
+                /**
+                 * Delay in milliseconds between retry attempts.
+                 */
+                delay: 1000,
+            },
+        },
+
+        /**
+         * Logging level for the pipeline.
+         */
+        logLevel: "info",
+    },
+
+    /**
+     * Default stages for the pipeline. Initially set to an empty array.
+     * Users can define and add their own stages.
+     */
+    stages: [],
+};

package/ts/core/index.ts

@@ -0,0 +1,34 @@
+// ============================================================================
+// Core Module Exports
+// ============================================================================
+
+/**
+ * Export core classes and modules for use in the application.
+ * Ensure all essential components are listed here to provide a unified API.
+ */
+
+// Core Classes
+export { Action } from "./pipeline/Action";
+export { Pipeline } from "./pipeline/Pipeline";
+export { PipelineManager } from "./pipeline/PipelineManager";
+export { Stage } from "./pipeline/Stage";
+export { Step } from "./pipeline/Step";
+
+// Utility Functions and Modules
+// If there are reusable utilities, add them here.
+// Example:
+// export { someUtilityFunction } from "./utils";
+
+// Action Registry
+// Export functions related to action registration and retrieval.
+// export {
+//     registerAction,
+//     getAction,
+//     listRegisteredActions
+// } from "../actions/ActionRegistry";
+
+/**
+ * Note: If new modules or files are added in the `core` directory,
+ * consider using an automated script to dynamically export them here.
+ * Tools like `barrel` can help maintain such an index file efficiently.
+ */

package/ts/core/pipeline/Action.ts

@@ -0,0 +1,101 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ActionInterface } from "../../interface/ActionInterface";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * Action is an abstract base class that serves as a foundation for all step
+ * actions in the pipeline. It provides a consistent structure and utility
+ * methods for derived action classes, making it easier to implement and
+ * integrate custom behaviors like `BuildAction`, `LintAction`, and more.
+ */
+export abstract class Action
+    extends AbstractProcess
+    implements ActionInterface
+{
+    // Parameters
+    // ========================================================================
+
+    /**
+     * Gets the unique name of the action.
+     * The name is derived from the class name of the concrete action.
+     */
+    public get name(): string {
+        return this.constructor.name;
+    }
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Constructs a new Action instance.
+     * Inherits the logger from the AbstractProcess base class.
+     */
+    constructor() {
+        super();
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Provides a basic validation mechanism for action options.
+     * Derived classes can override this method to implement specific
+     * validation logic.
+     *
+     * @param options - The options to validate, ensuring they meet the
+     * action"s specific requirements.
+     * @returns A boolean indicating whether the options are valid. Default
+     * implementation always returns true.
+     */
+    validateOptions(options: ActionOptionsType): boolean {
+        // Default validation: always returns true, can be overridden in
+        // derived classes
+        return true;
+    }
+
+    /**
+     * Abstract method that must be implemented by derived classes to perform
+     * the action"s main logic.
+     * This method is invoked during the step execution process.
+     *
+     * @param options - A structured set of options specific to the action's
+     * configuration.
+     * @returns A Promise that resolves when the action completes successfully,
+     * or rejects with an error if the action fails.
+     */
+    abstract execute(options: ActionOptionsType): Promise<void>;
+
+    /**
+     * Provides a summary or description of the action.
+     * This method can be overridden by derived classes to provide more
+     * specific details about the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Base action for executing steps in the pipeline.";
+    }
+
+    /**
+     * Logs a message indicating the start of the action's execution.
+     * Useful for tracking progress in pipelines with multiple steps.
+     */
+    protected logStart(): void {
+        this.logInfo(`Starting action: ${this.name}`);
+    }
+
+    /**
+     * Logs a message indicating the successful completion of the action.
+     */
+    protected logSuccess(): void {
+        this.logInfo(`Successfully completed action: ${this.name}`);
+    }
+}