kist 0.0.0 → 0.1.30

package/js/cli/ArgumentParser.d.ts

@@ -0,0 +1,62 @@
+import { AbstractProcess } from "../core/abstract/AbstractProcess";
+import { OptionsInterface } from "../interface/OptionsInterface";
+/**
+ * ArgumentParser handles parsing and validating command-line arguments
+ * against the structure defined in OptionsInterface.
+ * Extends AbstractProcess for consistent logging.
+ */
+export declare class ArgumentParser extends AbstractProcess {
+    /**
+     * Command-line arguments to parse, excluding the Node.js and script path.
+     */
+    private args;
+    /**
+     * Instance of OptionsValidator for validating parsed arguments.
+     */
+    private validator;
+    /**
+     * 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();
+    /**
+     * 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.
+     */
+    getOption<K extends keyof OptionsInterface>(key: K, options?: {
+        default?: OptionsInterface[K];
+    }): OptionsInterface[K] | undefined;
+    /**
+     * 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`.
+     */
+    hasFlag(key: keyof OptionsInterface): boolean;
+    /**
+     * 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.
+     */
+    getAllFlags(): Record<string, string | boolean>;
+    /**
+     * 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.
+     */
+    getFlag(key: string, defaultValue?: string | boolean): string | boolean;
+}

package/js/cli/ArgumentParser.js

@@ -0,0 +1,118 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArgumentParser = void 0;
+const AbstractProcess_1 = require("../core/abstract/AbstractProcess");
+const OptionsValidator_1 = require("../core/validation/OptionsValidator");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * ArgumentParser handles parsing and validating command-line arguments
+ * against the structure defined in OptionsInterface.
+ * Extends AbstractProcess for consistent logging.
+ */
+class ArgumentParser extends AbstractProcess_1.AbstractProcess {
+    // 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() {
+        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_1.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.
+     */
+    getOption(key, options) {
+        const flag = `--${key}`;
+        const flagIndex = this.args.findIndex((arg) => arg === flag);
+        const value = flagIndex !== -1 && this.args[flagIndex + 1]
+            ? this.args[flagIndex + 1]
+            : options === null || options === void 0 ? void 0 : options.default;
+        if (value !== undefined) {
+            // Create a partial object to validate the specific key-value pair
+            const partialOption = {
+                [key]: value,
+            };
+            // Validate the key-value pair
+            this.validator.validate(partialOption);
+        }
+        this.logInfo(`Retrieved option "${key}" with value: ${value}`);
+        return value;
+    }
+    /**
+     * 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`.
+     */
+    hasFlag(key) {
+        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.
+     */
+    getAllFlags() {
+        const flags = {};
+        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.
+     */
+    getFlag(key, defaultValue = false) {
+        var _a;
+        const flags = this.getAllFlags();
+        return (_a = flags[key]) !== null && _a !== void 0 ? _a : defaultValue;
+    }
+}
+exports.ArgumentParser = ArgumentParser;

package/js/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+export {};
+/**
+ * Note: The `#!/usr/bin/env node` shebang ensures that the script can be executed
+ * directly as a Node.js script on compatible systems.
+ */

package/js/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+"use strict";
+// ============================================================================
+// Imports
+// ============================================================================
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ArgumentParser_1 = require("./cli/ArgumentParser");
+const ConfigLoader_1 = require("./core/config/ConfigLoader");
+const ConfigStore_1 = require("./core/config/ConfigStore");
+const kist_1 = require("./kist");
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+/**
+ * The entry point for the Kist CLI application. Sets up the runtime
+ * environment, loads configuration, and invokes the Kist class.
+ */
+(() => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        // console.log("Raw arguments:", process.argv);
+        // Initialize CLI argument parser
+        const parser = new ArgumentParser_1.ArgumentParser();
+        const cliOptions = parser.getAllFlags();
+        // console.log(cliOptions)
+        // Initialize ConfigStore
+        const configStore = ConfigStore_1.ConfigStore.getInstance();
+        // Initialize ConfigStore and load configuration
+        const configLoader = new ConfigLoader_1.ConfigLoader();
+        yield configLoader.initialize();
+        const fileConfig = yield 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_1.Kist();
+        yield 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/js/core/abstract/AbstractProcess.d.ts

@@ -0,0 +1,62 @@
+import { Logger } from "../../logger/Logger";
+/**
+ * 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 declare abstract class AbstractProcess {
+    /**
+     * Logger instance for handling log messages.
+     */
+    protected readonly logger: Logger;
+    /**
+     * Constructs an AbstractProcess instance.
+     * Initializes the logger to ensure logging capabilities are available to
+     * subclasses.
+     */
+    constructor();
+    /**
+     * 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;
+    /**
+     * Logs a debug message with the originating class name as context.
+     * @param message - The debug message to log.
+     */
+    protected logDebug(message: string): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/js/core/abstract/AbstractProcess.js

@@ -0,0 +1,96 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractProcess = void 0;
+const Logger_1 = require("../../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.
+ */
+class AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Constructs an AbstractProcess instance.
+     * Initializes the logger to ensure logging capabilities are available to
+     * subclasses.
+     */
+    constructor() {
+        this.logger = Logger_1.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.
+     */
+    logInfo(message) {
+        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.
+     */
+    logDebug(message) {
+        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.
+     */
+    logWarn(message) {
+        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.
+     */
+    logError(message, error) {
+        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.
+     */
+    formatError(message, error) {
+        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.
+     */
+    logSuccess(message) {
+        this.logger.logInfo(this.constructor.name, message);
+    }
+}
+exports.AbstractProcess = AbstractProcess;

package/js/core/abstract/AbstractValidator.d.ts

@@ -0,0 +1,72 @@
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * 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 declare abstract class AbstractValidator<T> extends AbstractProcess {
+    constructor();
+    /**
+     * Validates an entire object.
+     * @param target - The object to validate.
+     * @throws Error if validation fails for any property.
+     */
+    validate(target: T): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/js/core/abstract/AbstractValidator.js

@@ -0,0 +1,128 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractValidator = void 0;
+const AbstractProcess_1 = require("../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.
+ */
+class AbstractValidator extends AbstractProcess_1.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.
+     */
+    validate(target) {
+        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, target[key]);
+            }
+        }
+        this.logInfo("Validation completed successfully.");
+    }
+    // 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.
+     */
+    validateNumber(key, value) {
+        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.
+     */
+    validateBoolean(key, value) {
+        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.
+     */
+    validateString(key, value) {
+        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.
+     */
+    validateObject(key, value) {
+        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.
+     */
+    logValidationSuccess(key, value) {
+        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.
+     */
+    throwValidationError(key, value, message) {
+        const errorMessage = `
+            Validation failed for "${String(key)}"
+            with value "${JSON.stringify(value)}".
+            ${message}
+        `;
+        this.logError(errorMessage);
+        throw new Error(errorMessage);
+    }
+}
+exports.AbstractValidator = AbstractValidator;

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

@@ -0,0 +1,47 @@
+import { ConfigInterface } from "../../interface/ConfigInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * 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 declare class ConfigLoader extends AbstractProcess {
+    /**
+     * Resolved path to the configuration file, if found.
+     */
+    private configPath;
+    /**
+     * Default filenames to search for configuration files.
+     */
+    private readonly defaultFilenames;
+    /**
+     * 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);
+    /**
+     * 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?: string): Promise<void>;
+    /**
+     * Loads and validates the configuration file.
+     *
+     * @returns Parsed and validated configuration object.
+     * @throws Error if the configuration file cannot be read or validated.
+     */
+    loadConfig(): Promise<ConfigInterface>;
+    /**
+     * Validates the structure of the configuration.
+     *
+     * @param config - The configuration object to validate.
+     * @throws Error if validation fails.
+     */
+    private validateConfig;
+}