kist 0.0.0 → 0.1.31

package/ts/cli/ArgumentParser.ts

@@ -0,0 +1,150 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { AbstractProcess } from "../core/abstract/AbstractProcess";
+import { OptionsValidator } from "../core/validation/OptionsValidator";
+import { OptionsInterface } from "../interface/OptionsInterface";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * ArgumentParser handles parsing and validating command-line arguments
+ * against the structure defined in OptionsInterface.
+ * Extends AbstractProcess for consistent logging.
+ */
+export class ArgumentParser extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * Command-line arguments to parse, excluding the Node.js and script path.
+     */
+    private args: string[];
+
+    /**
+     * Instance of OptionsValidator for validating parsed arguments.
+     */
+    private validator: OptionsValidator;
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Initializes the ArgumentParser with command-line arguments and an
+     * instance of OptionsValidator for validation.
+     *
+     * @param args - Command-line arguments. Defaults to `process.argv.slice(2)`.
+     */
+    constructor() { // args: string[] = process.argv.slice(2)
+        super();
+        // Skip Node.js and script path
+        this.args = process.argv.slice(2);
+
+        // console.log(process.argv.slice(2))
+
+        // this.args = args;
+        this.validator = new OptionsValidator();
+        this.logDebug("ArgumentParser initialized with arguments.");
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Retrieves the value of a specific option from the CLI arguments, with
+     * validation.
+     *
+     * @param key - The name of the option (matches keys in OptionsInterface).
+     * @param options - Additional options:
+     *  - `default`: The default value to return if the option is not found.
+     * @returns The value of the option or the default value if not found.
+     * @throws Error if the value is invalid based on the validation rules.
+     */
+    public getOption<K extends keyof OptionsInterface>(
+        key: K,
+        options?: { default?: OptionsInterface[K] },
+    ): OptionsInterface[K] | undefined {
+        const flag = `--${key}`;
+        const flagIndex = this.args.findIndex((arg) => arg === flag);
+        const value =
+            flagIndex !== -1 && this.args[flagIndex + 1]
+                ? this.args[flagIndex + 1]
+                : options?.default;
+
+        if (value !== undefined) {
+            // Create a partial object to validate the specific key-value pair
+            const partialOption = {
+                [key]: value,
+            } as Partial<OptionsInterface>;
+            // Validate the key-value pair
+            this.validator.validate(partialOption);
+        }
+
+        this.logInfo(`Retrieved option "${key}" with value: ${value}`);
+        return value as OptionsInterface[K];
+    }
+
+    /**
+     * Checks if a specific flag exists in the CLI arguments.
+     *
+     * @param key - The name of the flag to check (e.g., "dryRun").
+     * @returns `true` if the flag is present, otherwise `false`.
+     */
+    public hasFlag(key: keyof OptionsInterface): boolean {
+        const flag = `--${key}`;
+        const exists = this.args.includes(flag);
+        this.logInfo(
+            `Flag "${flag}" is ${exists ? "present" : "not present"}.`,
+        );
+        return exists;
+    }
+
+    /**
+     * Parses all CLI arguments into a key-value object.
+     * Flags are treated as boolean if not followed by a value.
+     *
+     * Example:
+     * --live --mode development => { live: true, mode: "development" }
+     *
+     * @returns A key-value object of all parsed CLI arguments.
+     */
+    public getAllFlags(): Record<string, string | boolean> {
+        const flags: Record<string, string | boolean> = {};
+
+        for (let i = 0; i < this.args.length; i++) {
+            const arg = this.args[i];
+            if (arg.startsWith("--")) {
+                const key = arg.slice(2);
+                const nextArg = this.args[i + 1];
+                if (nextArg && !nextArg.startsWith("--")) {
+                    flags[key] = nextArg;
+                    // Skip the next argument since it's a value
+                    i++;
+                } else {
+                    // Flag with no value is treated as boolean true
+                    flags[key] = true;
+                }
+            }
+        }
+
+        return flags;
+    }
+
+    /**
+     * Retrieves a specific flag value.
+     *
+     * @param key - The flag name to retrieve.
+     * @param defaultValue - The default value if the flag is not present.
+     * @returns The value of the flag or the default value.
+     */
+    public getFlag(
+        key: string,
+        defaultValue: string | boolean = false,
+    ): string | boolean {
+        const flags = this.getAllFlags();
+        return flags[key] ?? defaultValue;
+    }
+}

package/ts/cli/index.ts

@@ -0,0 +1 @@
+// export { getMode } from "./getMode";

package/ts/cli.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+// ============================================================================
+// Imports
+// ============================================================================
+
+import { ArgumentParser } from "./cli/ArgumentParser";
+import { ConfigLoader } from "./core/config/ConfigLoader";
+import { ConfigStore } from "./core/config/ConfigStore";
+import { Kist } from "./kist";
+
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+
+/**
+ * The entry point for the Kist CLI application. Sets up the runtime
+ * environment, loads configuration, and invokes the Kist class.
+ */
+(async () => {
+    try {
+        // console.log("Raw arguments:", process.argv);
+
+        // Initialize CLI argument parser
+        const parser = new ArgumentParser();
+        const cliOptions = parser.getAllFlags();
+        // console.log(cliOptions)
+
+        // Initialize ConfigStore
+        const configStore = ConfigStore.getInstance();
+
+        // Initialize ConfigStore and load configuration
+        const configLoader = new ConfigLoader();
+        await configLoader.initialize();
+        const fileConfig = await configLoader.loadConfig();
+
+        // Merge Configs
+        // configStore.print()
+        configStore.merge(fileConfig); // Merge file-based config
+        // configStore.print()
+        configStore.merge({ options: cliOptions }); // Merge CLI options
+        // configStore.print()
+
+        // Create a Kist instance and execute the workflow
+        const kist = new Kist();
+        await kist.run();
+    } catch (error) {
+        console.error(`[CLI] An unexpected error occurred:`, error);
+        process.exit(1);
+    }
+})();
+
+/**
+ * Note: The `#!/usr/bin/env node` shebang ensures that the script can be executed
+ * directly as a Node.js script on compatible systems.
+ */

package/ts/core/abstract/AbstractProcess.ts

@@ -0,0 +1,109 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { Logger } from "../../logger/Logger";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * AbstractProcess provides consistent logging functionality to its subclasses.
+ * It leverages a centralized logger to manage different log levels and
+ * ensures logging consistency across the application.
+ */
+export abstract class AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * Logger instance for handling log messages.
+     */
+    protected readonly logger: Logger;
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Constructs an AbstractProcess instance.
+     * Initializes the logger to ensure logging capabilities are available to
+     * subclasses.
+     */
+    constructor() {
+        this.logger = Logger.getInstance();
+    }
+
+    // Logging Methods
+    // ========================================================================
+
+    /**
+     * Logs an informational message with the originating class name as context.
+     * Use this for standard informational messages.
+     * @param message - The message to log.
+     */
+    protected logInfo(message: string): void {
+        this.logger.logInfo(this.constructor.name, message);
+    }
+
+    /**
+     * Logs a debug message with the originating class name as context.
+     * @param message - The debug message to log.
+     */
+    protected logDebug(message: string): void {
+        this.logger.logDebug(this.constructor.name, message);
+    }
+
+    /**
+     * Logs a warning message with the originating class name as context.
+     * Use this to highlight potential issues that are non-critical.
+     * @param message - The warning message to log.
+     */
+    protected logWarn(message: string): void {
+        this.logger.logWarn(this.constructor.name, message);
+    }
+
+    /**
+     * Logs an error message with the originating class name as context.
+     * Handles any type of error and ensures consistent error reporting.
+     * Use this for logging critical issues or exceptions.
+     *
+     * @param message - A custom message providing additional context for
+     * the error.
+     * @param error - (Optional) The error to log. Can be a string, an Error
+     * object, or other types.
+     */
+    protected logError(message: string, error?: unknown): void {
+        const errorMessage = this.formatError(message, error);
+        this.logger.logError(this.constructor.name, errorMessage);
+    }
+
+    /**
+     * Formats an error message for logging.
+     * Combines a custom message with additional error details if available.
+     *
+     * @param message - The base error message.
+     * @param error - Additional error information, such as an Error object.
+     * @returns A formatted string combining the message and error details.
+     */
+    private formatError(message: string, error?: unknown): string {
+        if (error instanceof Error) {
+            return `${message}: ${error.message}`;
+        } else if (typeof error === "string") {
+            return `${message}: ${error}`;
+        } else if (error) {
+            return `${message}: ${JSON.stringify(error)}`;
+        }
+        return message;
+    }
+
+    /**
+     * Logs a success message with the originating class name as context.
+     * Use this to indicate successful completion of a process or step.
+     *
+     * @param message - The success message to log.
+     */
+    protected logSuccess(message: string): void {
+        this.logger.logInfo(this.constructor.name, message);
+    }
+}

package/ts/core/abstract/AbstractSingleton.ts

@@ -0,0 +1,46 @@
+// ============================================================================
+// Abstract Singleton
+// ============================================================================
+
+/**
+ * AbstractSingleton provides a base class for implementing singletons.
+ * It ensures that only one instance of the derived class can exist.
+ */
+export abstract class AbstractSingleton<T extends AbstractSingleton<T>> {
+    private static _instances = new Map<string, AbstractSingleton<any>>();
+
+    protected constructor() {
+        const className = this.constructor.name;
+        if (AbstractSingleton._instances.has(className)) {
+            throw new Error(
+                `${className} is a singleton and has already been instantiated.`,
+            );
+        }
+        AbstractSingleton._instances.set(className, this);
+    }
+
+    /**
+     * Retrieves the singleton instance of the derived class.
+     * If no instance exists, it initializes one.
+     *
+     * @returns The singleton instance.
+     */
+    public static getInstance<T extends AbstractSingleton<T>>(
+        this: new () => T,
+    ): T {
+        const className = this.name;
+        if (!AbstractSingleton._instances.has(className)) {
+            AbstractSingleton._instances.set(className, new this());
+        }
+        return AbstractSingleton._instances.get(className) as T;
+    }
+
+    /**
+     * Clears the singleton instance, useful for testing or resetting state.
+     */
+    public static clearInstance<T extends AbstractSingleton<T>>(
+        this: new () => T,
+    ): void {
+        AbstractSingleton._instances.delete(this.name);
+    }
+}

package/ts/core/abstract/AbstractValidator.ts

@@ -0,0 +1,167 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { AbstractProcess } from "../abstract/AbstractProcess";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * AbstractValidator provides a base class for validation.
+ * Extends AbstractProcess for consistent logging and validation utility
+ * methods.
+ * Subclasses should implement the specific `validateProperty` method for
+ * custom validation logic.
+ */
+export abstract class AbstractValidator<T> extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    // Constructor
+    // ========================================================================
+
+    constructor() {
+        super();
+    }
+
+    // Abstract Methods
+    // ========================================================================
+
+    /**
+     * Validates an entire object.
+     * @param target - The object to validate.
+     * @throws Error if validation fails for any property.
+     */
+    public validate(target: T): void {
+        if (!target || typeof target !== "object") {
+            throw new Error("Target must be a valid object.");
+        }
+
+        for (const key in target) {
+            if (Object.prototype.hasOwnProperty.call(target, key)) {
+                this.validateProperty(key as keyof T, target[key as keyof T]);
+            }
+        }
+
+        this.logInfo("Validation completed successfully.");
+    }
+
+    /**
+     * Validates a specific property of the object.
+     * Subclasses must implement this method to provide specific validation logic.
+     *
+     * @param key - The key of the property being validated.
+     * @param value - The value of the property being validated.
+     */
+    protected abstract validateProperty<K extends keyof T>(
+        key: K,
+        value: T[K],
+    ): void;
+
+    // Validation Methods
+    // ========================================================================
+
+    /**
+     * Validates a numeric value.
+     *
+     * @param key - The key being validated.
+     * @param value - The numeric value to validate.
+     * @throws Error if the value is not a non-negative number.
+     */
+    protected validateNumber<K extends keyof T>(key: K, value: T[K]): void {
+        if (typeof value !== "number" || value < 0) {
+            this.throwValidationError(
+                key,
+                value,
+                "Must be a non-negative number.",
+            );
+        }
+    }
+
+    /**
+     * Validates a boolean value.
+     *
+     * @param key - The key being validated.
+     * @param value - The boolean value to validate.
+     * @throws Error if the value is not a boolean.
+     */
+    protected validateBoolean<K extends keyof T>(key: K, value: T[K]): void {
+        if (typeof value !== "boolean") {
+            this.throwValidationError(key, value, "Must be a boolean.");
+        }
+    }
+
+    /**
+     * Validates a string value.
+     *
+     * @param key - The key being validated.
+     * @param value - The string value to validate.
+     * @throws Error if the value is not a non-empty string.
+     */
+    protected validateString<K extends keyof T>(key: K, value: T[K]): void {
+        if (typeof value !== "string" || value.trim() === "") {
+            this.throwValidationError(
+                key,
+                value,
+                "Must be a non-empty string.",
+            );
+        }
+    }
+
+    /**
+     * Validates an object value.
+     *
+     * @param key - The key being validated.
+     * @param value - The object value to validate.
+     * @throws Error if the value is not a valid object.
+     */
+    protected validateObject<K extends keyof T>(key: K, value: T[K]): void {
+        if (
+            typeof value !== "object" ||
+            value === null ||
+            Array.isArray(value)
+        ) {
+            this.throwValidationError(key, value, "Must be a valid object.");
+        }
+    }
+
+    // Utility Methods
+    // ========================================================================
+
+    /**
+     * Logs validation success for a property.
+     * @param key - The property key.
+     * @param value - The value of the property.
+     */
+    protected logValidationSuccess(key: keyof T, value: T[keyof T]): void {
+        const message = `
+            Validation successful for property "${String(key)}"
+            with value: ${JSON.stringify(value)}
+            `;
+        this.logSuccess(message);
+    }
+
+    /**
+     * Throws a standardized validation error.
+     *
+     * @param key - The key being validated.
+     * @param value - The invalid value.
+     * @param message - Additional error message.
+     * @throws Error with a formatted message.
+     */
+    protected throwValidationError<K extends keyof T>(
+        key: K,
+        value: T[K],
+        message: string,
+    ): void {
+        const errorMessage = `
+            Validation failed for "${String(key)}"
+            with value "${JSON.stringify(value)}".
+            ${message}
+        `;
+        this.logError(errorMessage);
+        throw new Error(errorMessage);
+    }
+}

package/ts/core/config/ConfigLoader.ts

@@ -0,0 +1,141 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import fs from "fs";
+import yaml from "js-yaml";
+import path from "path";
+import { ConfigInterface } from "../../interface/ConfigInterface";
+import { AbstractProcess } from "../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.
+ */
+export class ConfigLoader extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * Resolved path to the configuration file, if found.
+     */
+    private configPath: string | null = null;
+
+    /**
+     * Default filenames to search for configuration files.
+     */
+    private readonly defaultFilenames = ["kist.yaml", "kist.yml"];
+
+    // 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?: string) {
+        super();
+        if (configPath) {
+            this.configPath = path.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.
+     */
+    public async initialize(configPath?: string): Promise<void> {
+        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.resolve(process.cwd(), fileName);
+            this.logDebug(`Checking: ${resolvedPath}`);
+
+            try {
+                await fs.promises.access(
+                    resolvedPath,
+                    fs.constants.F_OK | fs.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.
+     */
+    public async loadConfig(): Promise<ConfigInterface> {
+        if (!this.configPath) {
+            this.logWarn(
+                "No configuration file found. Using default configuration.",
+            );
+            return { stages: [] };
+        }
+
+        try {
+            this.logDebug(`Loading configuration from: ${this.configPath}`);
+            const fileContents = await fs.promises.readFile(
+                this.configPath,
+                "utf8",
+            );
+            const config = yaml.load(fileContents) as ConfigInterface;
+
+            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 as Error).message}`,
+            );
+        }
+    }
+
+    /**
+     * Validates the structure of the configuration.
+     *
+     * @param config - The configuration object to validate.
+     * @throws Error if validation fails.
+     */
+    private validateConfig(config: ConfigInterface): void {
+        if (!Array.isArray(config.stages)) {
+            throw new Error(
+                "Invalid configuration: 'stages' must be an array.",
+            );
+        }
+        this.logDebug("Configuration structure validated successfully.");
+    }
+}