kist 0.0.0 → 0.1.31

package/js/core/config/ConfigLoader.js

@@ -0,0 +1,130 @@
+"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.ConfigLoader = void 0;
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const path_1 = __importDefault(require("path"));
+const AbstractProcess_1 = require("../abstract/AbstractProcess");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * ConfigLoader is responsible for loading and parsing configuration files
+ * (`kist.yaml` or `kist.yml` by default). It validates the configuration
+ * structure and provides it in a usable format for the pipeline.
+ * Extends `AbstractProcess` for consistent logging.
+ */
+class ConfigLoader extends AbstractProcess_1.AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Constructs a ConfigLoader instance.
+     * Searches for `kist.yaml` or `kist.yml` in the working directory
+     * unless a custom path is provided.
+     *
+     * @param configPath - Optional custom configuration file path.
+     */
+    constructor(configPath) {
+        super();
+        // Parameters
+        // ========================================================================
+        /**
+         * Resolved path to the configuration file, if found.
+         */
+        this.configPath = null;
+        /**
+         * Default filenames to search for configuration files.
+         */
+        this.defaultFilenames = ["kist.yaml", "kist.yml"];
+        if (configPath) {
+            this.configPath = path_1.default.resolve(process.cwd(), configPath);
+            this.logDebug(`Custom configuration path set: ${this.configPath}`);
+        }
+        else {
+            this.logDebug("ConfigLoader initialized without custom path.");
+        }
+    }
+    // Methods
+    // ========================================================================
+    /**
+     * Initializes the loader by locating the configuration file.
+     * Searches for `kist.yaml` or `kist.yml` by default.
+     *
+     * @param configPath - Optional custom configuration file path.
+     */
+    initialize(configPath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const searchPaths = configPath ? [configPath] : this.defaultFilenames;
+            this.logDebug(`Current working directory: ${process.cwd()}`);
+            this.logDebug("Searching for configuration files...");
+            for (const fileName of searchPaths) {
+                const resolvedPath = path_1.default.resolve(process.cwd(), fileName);
+                this.logDebug(`Checking: ${resolvedPath}`);
+                try {
+                    yield fs_1.default.promises.access(resolvedPath, fs_1.default.constants.F_OK | fs_1.default.constants.R_OK);
+                    this.configPath = resolvedPath;
+                    this.logDebug(`Configuration file found: ${resolvedPath}`);
+                    return;
+                }
+                catch (error) {
+                    this.logDebug(`File not accessible: ${resolvedPath}`);
+                }
+            }
+            this.logWarn("No configuration file found. Proceeding with default settings.");
+        });
+    }
+    /**
+     * Loads and validates the configuration file.
+     *
+     * @returns Parsed and validated configuration object.
+     * @throws Error if the configuration file cannot be read or validated.
+     */
+    loadConfig() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.configPath) {
+                this.logWarn("No configuration file found. Using default configuration.");
+                return { stages: [] };
+            }
+            try {
+                this.logDebug(`Loading configuration from: ${this.configPath}`);
+                const fileContents = yield fs_1.default.promises.readFile(this.configPath, "utf8");
+                const config = js_yaml_1.default.load(fileContents);
+                this.validateConfig(config);
+                this.logDebug(`Successfully loaded configuration from: ${this.configPath}`);
+                return config;
+            }
+            catch (error) {
+                this.logError("Failed to load configuration.", error);
+                throw new Error(`Failed to load configuration: ${error.message}`);
+            }
+        });
+    }
+    /**
+     * Validates the structure of the configuration.
+     *
+     * @param config - The configuration object to validate.
+     * @throws Error if validation fails.
+     */
+    validateConfig(config) {
+        if (!Array.isArray(config.stages)) {
+            throw new Error("Invalid configuration: 'stages' must be an array.");
+        }
+        this.logDebug("Configuration structure validated successfully.");
+    }
+}
+exports.ConfigLoader = ConfigLoader;

package/js/core/config/ConfigStore.d.ts

@@ -0,0 +1,53 @@
+import { ConfigInterface } from "../../interface/ConfigInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * ConfigStore is a singleton that loads and manages the application's configuration.
+ * It prioritizes CLI arguments over configuration file values.
+ */
+export declare class ConfigStore extends AbstractProcess {
+    private static instance;
+    private config;
+    private constructor();
+    /**
+     * Retrieves the singleton instance of ConfigStore.
+     * @returns The singleton instance of ConfigStore.
+     */
+    static getInstance(): ConfigStore;
+    /**
+     * 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.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Sets a value in the configuration using dot notation.
+     *
+     * @param key - The key of the configuration to set.
+     * @param value - The value to set.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Merges the provided configuration into the existing configuration using deep merge.
+     *
+     * @param newConfig - The new configuration to merge.
+     */
+    merge(newConfig: Partial<ConfigInterface>): void;
+    /**
+     * Retrieves the current configuration object.
+     * @returns The current configuration.
+     */
+    getConfig(): ConfigInterface;
+    /**
+     * Prints the current configuration to the console.
+     */
+    print(): void;
+    /**
+     * Deeply merges two objects, preventing prototype pollution.
+     *
+     * @param target - The target object.
+     * @param source - The source object.
+     * @returns The merged object.
+     */
+    private deepMerge;
+}

package/js/core/config/ConfigStore.js

@@ -0,0 +1,136 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigStore = void 0;
+const AbstractProcess_1 = require("../abstract/AbstractProcess");
+const defaultConfig_1 = require("./defaultConfig");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * ConfigStore is a singleton that loads and manages the application's configuration.
+ * It prioritizes CLI arguments over configuration file values.
+ */
+class ConfigStore extends AbstractProcess_1.AbstractProcess {
+    // Constructor (Private to enforce Singleton Pattern)
+    constructor() {
+        super();
+        this.config = defaultConfig_1.defaultConfig;
+        this.logDebug("ConfigStore initialized with default configuration.");
+    }
+    /**
+     * Retrieves the singleton instance of ConfigStore.
+     * @returns The singleton instance of ConfigStore.
+     */
+    static getInstance() {
+        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.
+     */
+    get(key) {
+        const keys = key.split(".");
+        let current = this.config;
+        for (const k of keys) {
+            if (current[k] === undefined) {
+                return undefined;
+            }
+            current = current[k];
+        }
+        this.logDebug(`Configuration key "${key}" retrieved.`);
+        return current;
+    }
+    /**
+     * Sets a value in the configuration using dot notation.
+     *
+     * @param key - The key of the configuration to set.
+     * @param value - The value to set.
+     */
+    set(key, value) {
+        const keys = key.split(".");
+        let current = 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.
+     */
+    merge(newConfig) {
+        this.config = this.deepMerge(this.config, newConfig);
+        this.logDebug("Configuration successfully merged.");
+    }
+    /**
+     * Retrieves the current configuration object.
+     * @returns The current configuration.
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Prints the current configuration to the console.
+     */
+    print() {
+        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.
+     */
+    deepMerge(target, source) {
+        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;
+    }
+}
+exports.ConfigStore = ConfigStore;
+// Singleton instance
+ConfigStore.instance = null;

package/js/core/config/defaultConfig.d.ts

@@ -0,0 +1,5 @@
+import { ConfigInterface } from "../../interface/ConfigInterface";
+/**
+ * Default configuration for the kist pipeline.
+ */
+export declare const defaultConfig: ConfigInterface;

package/js/core/config/defaultConfig.js

@@ -0,0 +1,131 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfig = void 0;
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Default configuration for the kist pipeline.
+ */
+exports.defaultConfig = {
+    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/js/core/pipeline/Action.d.ts

@@ -0,0 +1,60 @@
+import { ActionInterface } from "../../interface/ActionInterface";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * 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 declare abstract class Action extends AbstractProcess implements ActionInterface {
+    /**
+     * Gets the unique name of the action.
+     * The name is derived from the class name of the concrete action.
+     */
+    get name(): string;
+    /**
+     * Constructs a new Action instance.
+     * Inherits the logger from the AbstractProcess base class.
+     */
+    constructor();
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Logs a message indicating the start of the action's execution.
+     * Useful for tracking progress in pipelines with multiple steps.
+     */
+    protected logStart(): void;
+    /**
+     * Logs a message indicating the successful completion of the action.
+     */
+    protected logSuccess(): void;
+}

package/js/core/pipeline/Action.js

@@ -0,0 +1,77 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Action = void 0;
+const AbstractProcess_1 = require("../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.
+ */
+class Action extends AbstractProcess_1.AbstractProcess {
+    // Parameters
+    // ========================================================================
+    /**
+     * Gets the unique name of the action.
+     * The name is derived from the class name of the concrete action.
+     */
+    get name() {
+        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) {
+        // Default validation: always returns true, can be overridden in
+        // derived classes
+        return true;
+    }
+    /**
+     * 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() {
+        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.
+     */
+    logStart() {
+        this.logInfo(`Starting action: ${this.name}`);
+    }
+    /**
+     * Logs a message indicating the successful completion of the action.
+     */
+    logSuccess() {
+        this.logInfo(`Successfully completed action: ${this.name}`);
+    }
+}
+exports.Action = Action;

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

@@ -0,0 +1,80 @@
+import { ActionInterface } from "../../interface/ActionInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * 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 declare class ActionRegistry extends AbstractProcess {
+    /**
+     * Singleton instance
+     */
+    private static instance;
+    /**
+     * Map to store registered actions
+     */
+    private registry;
+    /**
+     * Constructs an ActionRegistry instance and automatically registers core
+     * actions. The constructor is private to enforce the singleton pattern.
+     */
+    constructor();
+    /**
+     * 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(): void;
+    /**
+     * Retrieves the singleton instance of ActionRegistry, initializing it if
+     * necessary.
+     *
+     * @returns The ActionRegistry instance.
+     */
+    static getInstance(): ActionRegistry;
+    /**
+     * Resets the singleton instance of ActionRegistry.
+     * This is useful for testing or resetting the registry state during
+     * runtime.
+     */
+    static resetInstance(): void;
+    /**
+     * 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: new () => ActionInterface): void;
+    /**
+     * 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: string): (new () => ActionInterface) | undefined;
+    /**
+     * 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(): string[];
+    /**
+     * 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;
+    private discoverPlugins;
+    /**
+     * Clears all registered actions in the registry.
+     * Useful for testing or resetting the pipeline.
+     */
+    clearRegistry(): void;
+}