kist 0.0.0 → 0.1.30

package/js/interface/MetadataInterface.d.ts

@@ -0,0 +1,95 @@
+/**
+ * MetadataInterface provides contextual information about the pipeline
+ * configuration. This metadata is useful for tracking changes, documentation,
+ * and integration with external systems.
+ */
+export interface MetadataInterface {
+    /**
+     * A human-readable name for the pipeline.
+     * Used for identification and reporting purposes.
+     *
+     * @example "Data Processing Pipeline"
+     */
+    name?: string;
+    /**
+     * The semantic version of the pipeline configuration.
+     * Helps in tracking changes, maintaining compatibility, and managing
+     * different setups.
+     *
+     * @example "1.0.0"
+     */
+    version?: string;
+    /**
+     * A detailed description outlining the pipeline's purpose, objectives,
+     * or key features.
+     * Useful for providing context to users and maintainers.
+     *
+     * @example "A pipeline for processing and analyzing large datasets,
+     * including ETL operations."
+     */
+    description?: string;
+    /**
+     * The author or owner of the pipeline configuration.
+     * Can include details such as name, email, or organization.
+     *
+     * @example "John Doe <john.doe@example.com>"
+     */
+    author?: string;
+    /**
+     * A collection of arbitrary key-value pairs to further describe the
+     * pipeline configuration. This can be used for categorization or
+     * custom metadata.
+     *
+     * @example { category: "ETL", team: "Data Engineering" }
+     */
+    tags?: Record<string, string>;
+    /**
+     * A timestamp indicating when the configuration was created or last
+     * updated. Should follow the ISO 8601 format (e.g.,
+     * "2024-01-01T12:00:00Z").
+     *
+     * @example "2024-01-01T12:00:00Z"
+     */
+    timestamp?: string;
+    /**
+     * The license under which the pipeline configuration is shared or used.
+     * This defines the terms and conditions for using the configuration.
+     *
+     * @example "MIT"
+     * @example "GPL-3.0"
+     */
+    license?: string;
+    /**
+     * A URL pointing to documentation or additional resources related to
+     * the pipeline.
+     * Can include links to GitHub repos, wikis, or help pages.
+     *
+     * @example "https://github.com/username/repo"
+     */
+    documentation?: string;
+    /**
+     * Contact information for questions or support regarding the pipeline
+     * configuration.
+     * This can include an email address, a support page URL, or a
+     * team/organization name.
+     *
+     * @example "support@example.com"
+     * @example "https://example.com/support"
+     */
+    contact?: string;
+    /**
+     * Dependencies or related systems required by the pipeline configuration.
+     * Useful for tracking external systems or tools that interact with this
+     * pipeline.
+     *
+     * @example ["Node.js >=14.0", "Docker >=20.10"]
+     */
+    dependencies?: string[];
+    /**
+     * A list of intended runtime environment(s) for the pipeline.
+     * This helps clarify where the pipeline is designed to be executed.
+     *
+     * @example ["local", "CI/CD", "staging", "production"]
+     */
+    environments?: string[];
+}

package/js/interface/MetadataInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/interface/OptionsInterface.d.ts

@@ -0,0 +1,45 @@
+import { LiveOptionsInterface } from "./LiveOptionsInterface";
+import { PipelineOptionsInterface } from "./PipelineOptionsInterface";
+/**
+ * OptionsInterface represents the global configuration options that
+ * apply to the entire pipeline. These settings provide overarching controls
+ * that affect how all stages and steps within the pipeline operate.
+ */
+export interface OptionsInterface {
+    /**
+     * Configuration settings for live reload functionality, enabling
+     * real-time updates during development.
+     */
+    live?: LiveOptionsInterface;
+    /**
+     * Pipeline-specific configuration options.
+     */
+    pipeline?: PipelineOptionsInterface;
+    /**
+     * Path to the configuration file. This can be used to override default
+     * or automatically located configuration files.
+     *
+     * @example "./config/pack.yaml"
+     */
+    configPath?: string;
+    /**
+     * Specifies the level of logging to be used throughout the pipeline.
+     *
+     * The available levels are:
+     * - "debug": Provides detailed logging, useful for debugging and
+     *      tracing execution flow.
+     * - "info": Standard logging level, providing key information about
+     *      pipeline progress and outcomes.
+     * - "warn": Logs only warnings and errors, useful for highlighting
+     *      potential issues without excessive details.
+     * - "error": Logs only errors, minimizing output to essential problem
+     *      notifications. Default is "info".
+     *
+     * @default "info"
+     */
+    logLevel?: "debug" | "info" | "warn" | "error";
+    /**
+     * Additional properties can be included dynamically.
+     */
+    [key: string]: unknown;
+}

package/js/interface/OptionsInterface.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/interface/PipelineOptionsInterface.d.ts

@@ -0,0 +1,66 @@
+/**
+ * PipelineOptionsInterface defines settings for managing the pipeline's
+ * execution behavior, including timeouts, failure handling, concurrency,
+ * and retry strategies.
+ */
+export interface PipelineOptionsInterface {
+    /**
+     * Default timeout in milliseconds for each step within the pipeline.
+     *
+     * If a step exceeds this duration, it will be forcibly terminated to
+     * prevent blocking the pipeline. This setting helps manage steps that
+     * might hang or take longer than expected.
+     *
+     * @default 30000
+     * @example 15000
+     */
+    stepTimeout?: number;
+    /**
+     * Specifies whether to halt the entire pipeline if a step fails.
+     * - true: The pipeline will stop execution immediately upon encountering
+     *      a failed step.
+     * - false: The pipeline will continue executing subsequent steps and
+     *      stages despite errors.
+     *
+     * Default is true (halt on failure), ensuring the pipeline stops at the
+     * first sign of trouble.
+     *
+     * @default true
+     */
+    haltOnFailure?: boolean;
+    /**
+     * Specifies the maximum number of concurrent stages allowed to run in
+     * parallel. This setting controls resource usage and can help prevent
+     * overloading the system.
+     *
+     * - `0` or `undefined`: No limit, all stages run in parallel (as allowed
+     *   by their dependencies).
+     * - A positive integer: Limits the number of stages that can run
+     *   simultaneously.
+     *
+     * @default undefined
+     */
+    maxConcurrentStages?: number;
+    /**
+     * Specifies a retry strategy for steps that fail.
+     *
+     * - `retries`: Number of retry attempts before marking a step as failed.
+     * - `delay`: Time in milliseconds between retry attempts.
+     *
+     * This allows automatic retries for temporary failures, improving
+     * pipeline robustness.
+     *
+     * @default { retries: 0, delay: 0 }
+     * @example { retries: 3, delay: 1000 }
+     */
+    retryStrategy?: {
+        /**
+         * Number of retry attempts before marking a step as failed.
+         */
+        retries: number;
+        /**
+         * Time in milliseconds between retry attempts.
+         */
+        delay: number;
+    };
+}

package/js/interface/PipelineOptionsInterface.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// Interfaces
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/interface/StageInterface.d.ts

@@ -0,0 +1,79 @@
+import { StepInterface } from "./StepInterface";
+/**
+ * StageInterface represents a stage in the packaging pipeline, consisting of
+ * multiple steps. Each stage serves as a logical grouping of related steps,
+ * providing a structured way to organize the pipeline execution flow. Stages
+ * can have dependencies on other stages, allowing for complex sequencing of
+ * actions within the pipeline.
+ */
+export interface StageInterface {
+    /**
+     * A unique identifier for the stage, used for logging, tracking, and
+     * reporting purposes. The name should be descriptive enough to clearly
+     * convey the purpose of the stage.
+     */
+    name: string;
+    /**
+     * An ordered array of steps that comprise the stage.
+     * Steps are executed consecutively within the stage, following the order
+     * they are defined in. Each step is expected to implement the
+     * StepInterface, providing specific actions to be performed.
+     */
+    steps: StepInterface[];
+    /**
+     * An optional list of stage names that this stage depends on.
+     * The current stage will not begin execution until all specified dependent
+     * stages have completed successfully. This allows for orchestrating
+     * complex dependencies and ensuring proper sequencing of stages in the
+     * pipeline.
+     */
+    dependsOn?: string[];
+    /**
+     * An optional description of the stage, providing additional context and
+     * details about what the stage is intended to accomplish. Useful for
+     * documentation, logging, and understanding the overall pipeline flow.
+     */
+    description?: string;
+    /**
+     * An optional flag to control whether the stage should be executed.
+     * This can be used to conditionally skip stages based on dynamic criteria,
+     * such as environment settings or previous results.
+     * Default is true (stage will be executed).
+     */
+    enabled?: boolean;
+    /**
+     * Optional timeout for the entire stage, specified in milliseconds.
+     * If the stage exceeds this duration, it will be forcibly terminated to
+     * prevent blocking the pipeline indefinitely. Helps manage long-running
+     * stages and ensures the pipeline maintains predictable execution times.
+     */
+    timeout?: number;
+    /**
+     * Priority level for the stage, used to influence execution order in
+     * concurrent scenarios. Higher priority stages may execute before lower
+     * priority ones when multiple stages are eligible to run simultaneously.
+     * Default: `'normal'`.
+     * - `'low'`: Lower execution priority.
+     * - `'normal'`: Default execution priority.
+     * - `'high'`: Higher execution priority.
+     */
+    priority?: "low" | "normal" | "high";
+    /**
+     * Optional tags to attach metadata or labels to the stage. Tags can be
+     * used for filtering, reporting, or integration with external tools that
+     * require context or categorization.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Optional hooks that allow custom logic to be executed before or after
+     * the stage.
+     * Useful for injecting custom behavior or performing additional
+     * setup/cleanup tasks.
+     * - `before`: Function to run before the stage starts.
+     * - `after`: Function to run after the stage completes.
+     */
+    hooks?: {
+        before?: () => Promise<void> | void;
+        after?: () => Promise<void> | void;
+    };
+}

package/js/interface/StageInterface.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/interface/StepInterface.d.ts

@@ -0,0 +1,66 @@
+import { ActionInterface } from "./ActionInterface";
+import { StepOptionsInterface } from "./StepOptionsInterface";
+/**
+ * StepInterface defines a single executable unit within a pipeline stage.
+ * Each step encapsulates a specific action to be performed, along with
+ * configuration options that tailor its behavior. Steps are executed in
+ * sequence within their respective stages.
+ */
+export interface StepInterface {
+    /**
+     * A unique identifier for the step, used for logging, debugging, and
+     * reporting. This name should be descriptive and clearly indicate the
+     * purpose of the step.
+     */
+    name: string;
+    /**
+     * The action that this step will perform, represented by a class
+     * implementing the ActionInterface. This action defines the core
+     * functionality of the step, such as building, testing, or deploying.
+     * The action is responsible for executing the main logic associated with
+     * the step.
+     */
+    action: ActionInterface;
+    /**
+     * Optional configuration options specific to the step.
+     * These options allow customization of the step's behavior, providing
+     * flexibility to adapt the action to different contexts or requirements.
+     * For example, build steps might accept options for minification or target
+     * environments.
+     */
+    options?: StepOptionsInterface;
+    /**
+     * An optional flag to enable or disable this step dynamically.
+     * - `true`: Step will be executed (default behavior).
+     * - `false`: Step will be skipped during execution.
+     */
+    enabled?: boolean;
+    /**
+     * Optional timeout for this step, specified in milliseconds.
+     * If the step exceeds this duration, it will be forcibly terminated,
+     * ensuring the pipeline remains predictable and responsive.
+     */
+    timeout?: number;
+    /**
+     * An optional description providing additional context or details about
+     * the step. Useful for documentation, reporting, or explaining the
+     * purpose of the step to maintainers.
+     */
+    description?: string;
+    /**
+     * An optional set of tags to provide metadata for the step.
+     * Tags can be used for logging, filtering, or integrating with external
+     * tools and systems that require context.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Optional hooks to execute custom logic before or after the step.
+     * Hooks can be used for additional setup, teardown, or condition checks.
+     * - `before`: Function executed before the step runs.
+     * - `after`: Function executed after the step completes.
+     */
+    hooks?: {
+        before?: () => Promise<void> | void;
+        after?: () => Promise<void> | void;
+    };
+}

package/js/interface/StepInterface.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/interface/StepOptionsInterface.d.ts

@@ -0,0 +1,38 @@
+/**
+ * StepOptionsInterface represents the configuration options for a step,
+ * allowing customization of the step's behavior through specific parameters
+ * and settings. This interface can be extended for action-specific options,
+ * providing type safety and clarity for different configurations used within
+ * the packaging pipeline.
+ */
+export interface StepOptionsInterface {
+    /**
+     * An optional description of the step, useful for logging, debugging, and
+     * reporting. This provides additional context about the step's purpose and
+     * configuration.
+     */
+    description?: string;
+    /**
+     * Specifies whether the step should be enabled or skipped.
+     * This can be used to conditionally execute steps based on dynamic
+     * criteria.
+     * Default is true (enabled).
+     */
+    enabled?: boolean;
+}
+/**
+ * Recommendations for Extending StepOptionsInterface:
+ * - For specific actions, extend `StepOptionsInterface` to add detailed types
+ *   and enforce stricter validation.
+ *
+ * Example:
+ * ```typescript
+ * export interface BuildStepOptions extends StepOptionsInterface {
+ *     minify?: boolean;
+ *     target?: 'es5' | 'es6' | 'es2020';
+ *     sourceMap?: boolean;
+ * }
+ * ```
+ *
+ * This approach ensures type safety while maintaining flexibility for general steps.
+ */

package/js/interface/StepOptionsInterface.js

@@ -0,0 +1,21 @@
+"use strict";
+// ============================================================================
+// Interfaces
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Recommendations for Extending StepOptionsInterface:
+ * - For specific actions, extend `StepOptionsInterface` to add detailed types
+ *   and enforce stricter validation.
+ *
+ * Example:
+ * ```typescript
+ * export interface BuildStepOptions extends StepOptionsInterface {
+ *     minify?: boolean;
+ *     target?: 'es5' | 'es6' | 'es2020';
+ *     sourceMap?: boolean;
+ * }
+ * ```
+ *
+ * This approach ensures type safety while maintaining flexibility for general steps.
+ */

package/js/interface/index.d.ts

@@ -0,0 +1,7 @@
+export { ActionInterface } from "./ActionInterface";
+export { ConfigInterface } from "./ConfigInterface";
+export { LiveOptionsInterface } from "./LiveOptionsInterface";
+export { OptionsInterface } from "./OptionsInterface";
+export { StageInterface } from "./StageInterface";
+export { StepInterface } from "./StepInterface";
+export { StepOptionsInterface } from "./StepOptionsInterface";

package/js/interface/index.js

@@ -0,0 +1,3 @@
+"use strict";
+// Exporting all interfaces from the interfaces directory
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/kist.d.ts

@@ -0,0 +1,58 @@
+import { AbstractProcess } from "./core/abstract/AbstractProcess";
+/**
+ * The Kist class encapsulates the kist CLI functionality.
+ * It manages the pipeline execution, configuration loading, and live reload.
+ */
+export declare class Kist extends AbstractProcess {
+    /**
+     * Constructs the Kist class instance and initializes necessary components.
+     */
+    constructor();
+    /**
+     * Executes the Kist workflow.
+     *
+     * This method orchestrates the execution of the Kist pipeline, starting
+     * from initializing the ActionRegistry, loading configuration settings,
+     * running the pipeline stages through the `PipelineManager`, and
+     * optionally enabling live reload for real-time updates.
+     *
+     * @returns {Promise<void>} Resolves when the workflow completes successfully.
+     * @example
+     * const Kist = new Kist();
+     * Kist.run().then(() => console.log("Pipeline execution complete."));
+     */
+    run(): Promise<void>;
+    /**
+     * Initializes the ActionRegistry with available actions.
+     * Automatically registers core actions and discovers external plugins.
+     */
+    private initializeActionRegistry;
+    /**
+     * Sets up live reload functionality.
+     * Monitors file changes and restarts the pipeline when updates are detected.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    private setupLiveReload;
+    /**
+     * Registers handlers for graceful shutdown signals.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    private registerShutdownHandlers;
+    /**
+     * Handles graceful shutdown of the pipeline and live reload server.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    private handleShutdown;
+    /**
+     * Handles errors occurring during the execution of the Kist workflow.
+     *
+     * @param error - The error object to log and handle.
+     */
+    private handleError;
+}

package/js/kist.js

@@ -0,0 +1,145 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Kist = void 0;
+const AbstractProcess_1 = require("./core/abstract/AbstractProcess");
+const ConfigStore_1 = require("./core/config/ConfigStore");
+const ActionRegistry_1 = require("./core/pipeline/ActionRegistry");
+const PipelineManager_1 = require("./core/pipeline/PipelineManager");
+const LiveServer_1 = require("./live/LiveServer");
+const LiveWatcher_1 = require("./live/LiveWatcher");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * The Kist class encapsulates the kist CLI functionality.
+ * It manages the pipeline execution, configuration loading, and live reload.
+ */
+class Kist extends AbstractProcess_1.AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Constructs the Kist class instance and initializes necessary components.
+     */
+    constructor() {
+        super();
+        this.logDebug("Kist initialized.");
+    }
+    // Methods
+    // ========================================================================
+    /**
+     * Executes the Kist workflow.
+     *
+     * This method orchestrates the execution of the Kist pipeline, starting
+     * from initializing the ActionRegistry, loading configuration settings,
+     * running the pipeline stages through the `PipelineManager`, and
+     * optionally enabling live reload for real-time updates.
+     *
+     * @returns {Promise<void>} Resolves when the workflow completes successfully.
+     * @example
+     * const Kist = new Kist();
+     * Kist.run().then(() => console.log("Pipeline execution complete."));
+     */
+    run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logInfo("Starting Kist workflow...");
+            try {
+                // Initialize the ActionRegistry with available actions
+                this.initializeActionRegistry();
+                // Create and run the PipelineManager
+                const liveReloadEnabled = ConfigStore_1.ConfigStore.getInstance().get("options.live.enabled");
+                const liveReloadServer = liveReloadEnabled
+                    ? new LiveServer_1.LiveServer()
+                    : null;
+                const pipelineManager = new PipelineManager_1.PipelineManager(liveReloadServer);
+                yield pipelineManager.runPipeline();
+                // Setup live reload if enabled
+                if (liveReloadEnabled) {
+                    this.setupLiveReload(pipelineManager, liveReloadServer);
+                }
+            }
+            catch (error) {
+                this.handleError(error);
+            }
+        });
+    }
+    /**
+     * Initializes the ActionRegistry with available actions.
+     * Automatically registers core actions and discovers external plugins.
+     */
+    initializeActionRegistry() {
+        this.logInfo("Initializing ActionRegistry...");
+        ActionRegistry_1.ActionRegistry.initialize();
+        this.logInfo("ActionRegistry initialized successfully.");
+    }
+    /**
+     * Sets up live reload functionality.
+     * Monitors file changes and restarts the pipeline when updates are detected.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    setupLiveReload(pipelineManager, liveReloadServer) {
+        this.logInfo("Enabling live reload functionality...");
+        new LiveWatcher_1.LiveWatcher((filePath) => {
+            this.logInfo(`Detected change in: ${filePath}. Restarting pipeline...`);
+            pipelineManager.restartPipelineWithDelay(500);
+        });
+        pipelineManager.restartPipeline();
+        this.registerShutdownHandlers(pipelineManager, liveReloadServer);
+    }
+    /**
+     * Registers handlers for graceful shutdown signals.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    registerShutdownHandlers(pipelineManager, liveReloadServer) {
+        process.on("SIGINT", () => this.handleShutdown(pipelineManager, liveReloadServer));
+        process.on("SIGTERM", () => this.handleShutdown(pipelineManager, liveReloadServer));
+    }
+    /**
+     * Handles graceful shutdown of the pipeline and live reload server.
+     *
+     * @param pipelineManager - The manager responsible for the pipeline process.
+     * @param liveReloadServer - The server for live reload connections.
+     */
+    handleShutdown(pipelineManager, liveReloadServer) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logInfo("Shutdown signal received. Shutting down...");
+            try {
+                yield pipelineManager.stopPipeline();
+                yield liveReloadServer.shutdown();
+                this.logInfo("Shutdown completed successfully.");
+            }
+            catch (error) {
+                this.logError("Error during shutdown.", error);
+            }
+            finally {
+                process.exit(0);
+            }
+        });
+    }
+    /**
+     * Handles errors occurring during the execution of the Kist workflow.
+     *
+     * @param error - The error object to log and handle.
+     */
+    handleError(error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logError(`An error occurred: ${errorMessage}`, error);
+        process.exit(1);
+    }
+}
+exports.Kist = Kist;