kist 0.0.0 → 0.1.30

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Scape Agency
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,303 @@
-# KIST - TypeScript & SCSS Package Manager
+<p align="center">
+    <img src="https://raw.githubusercontent.com/getkist/brand/master/src/logo/kist.png" width="20%" height="20%" alt="kist logo"></p>
+<h1 align="center" style='border-bottom: none;'>kist</h1>
+<h3 align="center">Package Pipeline Processor</h3>
 
-KIST is a TypeScript and SCSS package manager.
+<br/>
+
+<div align="center">
+
+[![Website](https://img.shields.io/website?url=https%3A%2F%2Fwww.kist&up_message=Up&up_color=5e4d34&down_message=Down&down_color=5e4d34&style=flat-square&logo=Firefox&logoColor=FFFFFF&label=Website&labelColor=5e4d34&color=5e4d34)
+](https://www.kist)
+[![NPM Version](https://img.shields.io/npm/v/kist?style=flat-square&logo=npm&logoColor=FFFFFF&label=NPM&labelColor=5e4d34&color=5e4d34&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2Fkist)](https://www.npmjs.com/package/kist)
+[![devContainer](https://img.shields.io/badge/devContainer-235e4d34?style=flat-square&logo=Docker&logoColor=%23FFFFFF&labelColor=%235e4d34&color=%235e4d34)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/getkist/kist)
+[![StackBlitz](https://img.shields.io/badge/StackBlitz-235e4d34?style=flat-square&logo=StackBlitz&logoColor=%23FFFFFF&labelColor=%235e4d34&color=%235e4d34)](https://stackblitz.com/github/getkist/kist/tree/main?file=src%2Findex.html)
+[![GitHub License](https://img.shields.io/github/license/getkist/kist?style=flat-square&logo=readthedocs&logoColor=FFFFFF&label=&labelColor=%235e4d34&color=%235e4d34&link=LICENSE)](https://github.com/getkist/kist/blob/main/LICENSE)
+
+</div>
+
+<div align="center">
+
+[![Report a Bug](https://img.shields.io/badge/Report%20a%20Bug-GitHub?style=flat-square&&logoColor=%23FFFFFF&color=%23D2D9DF)](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=bug_report.yml)
+[![Request a Feature](https://img.shields.io/badge/Request%20a%20Feature-GitHub?style=flat-square&&logoColor=%23FFFFFF&color=%23D2D9DF)](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=feature_request.yml)
+[![Ask a Question](https://img.shields.io/badge/Ask%20a%20Question-GitHub?style=flat-square&&logoColor=%23FFFFFF&color=%23D2D9DF)](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=question.yml)
+[![Make a Suggestion](https://img.shields.io/badge/Make%20a%20Suggestion-GitHub?style=flat-square&&logoColor=%23FFFFFF&color=%23D2D9DF)](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=suggestion.yml)
+[![Start a Discussion](https://img.shields.io/badge/Start%20a%20Discussion-GitHub?style=flat-square&&logoColor=%23FFFFFF&color=%23D2D9DF)](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=discussion.yml)
+
+</div>
+
+---
+
+<br/>
+
+kist is a highly customizable and efficient package builder designed to streamline software development workflows. It provides a modular framework for managing build pipelines with support for live reload functionality.
+
+`kist` is a package builder designed to enhance the efficiency and organization of software development projects. Key to its design philosophy is the adaptability to various development workflows, making it an ideal companion for a range of projects from small-scale personal endeavors to large, complex enterprise applications. `kist` stands not just as a tool but as a partner in the software development journey, enhancing productivity, reducing overhead, and bringing clarity and ease to the package management process.
+
+---
+
+## Features
+
+- Modular pipeline system with stages and steps.
+- Live reload functionality for enhanced developer experience.
+- Plugin-based architecture to extend functionality.
+- TypeScript support for a modern development workflow.
+- Robust error handling and logging.
+
+---
+
+## Quickstart
+
+To install `kist`, use npm or yarn:
+
+### NPM
+
+```bash
+npm install kist --save-dev
+```
+
+### Yarn
+
+```bash
+yarn add kist --dev
+```
+
+---
 
 ## Installation
 
+1. Clone the Repository:
+
+    ```sh
+    git clone <https://github.com/getkist/kist.git>
+    cd kist
+    ```
+
+2. Install Dependencies:
+
+    ```sh
+    npm install
+    ```
+
+3. Build the Project:
+
+    ```sh
+    npm run build
+    ```
+
+4. Link the CLI Globally:
+
+    ```sh
+    npm link
+    ```
+
+---
+
+## Usage
+
+### Run the Pipeline
+
+Run the pipeline defined in your pack.yaml file:
+
+```sh
+pack
+```
+
+### Enable Live Reload
+
+Run the pipeline with live reload enabled:
+
+```sh
+pack --live
+```
+
+---
+
+## Configuration
+
+The pipeline configuration is defined in a pack.yaml file located in the root of your project. Here’s an example:
+
+```sh
+stages:
+
+- name: build
+    steps:
+  - name: compile
+        action: build
+        options:
+          source: src/
+          output: dist/
+- name: test
+    dependsOn: [build]
+    steps:
+  - name: run-tests
+        action: test
+```
+
+Stage and Step Structure
+
+- Stages: Define a group of steps to be executed.
+- Steps: Individual tasks within a stage (e.g., compiling, testing).
+- Dependencies: Stages can depend on other stages to enforce execution order.
+
+---
+
+## Development
+
+### Build
+
+Compile the TypeScript files into JavaScript:
+
+```sh
+npm run build-tsc
+```
+
+### Lint
+
+Run ESLint to check for code issues:
+
+```sh
+npm run lint
+```
+
+### Run Tests
+
+Run all tests in the src/tests directory:
+
+```sh
+npm run test
+```
+
+### Live Reload
+
+To enable live reload during development, add the --live flag:
+
+```sh
+pack --live
+```
+
+---
+
+## Folder Structure
+
 ```sh
-npm install kist
+kist/
+├── src/
+│   ├── core/           # Core pipeline logic
+│   ├── live/           # Live reload server and related components
+│   ├── actions/        # Built-in step actions (e.g., build, test)
+│   ├── tests/          # Unit tests
+│   └── pack.ts         # Entry point for the CLI
+├── dist/               # Compiled JavaScript output
+├── pack.yaml           # Example configuration file
+├── package.json        # Project metadata and dependencies
+├── tsconfig.json       # TypeScript configuration
+└── README.md           # Project documentation
+```
+
+---
+
+## Key Components
+
+### Pipeline
+
+The Pipeline class manages the execution of stages and steps defined in the pack.yaml file.
+
+### LiveReloadServer
+
+The LiveReloadServer provides live reload functionality by watching files for changes and notifying connected clients.
+
+### ConfigLoader
+
+The ConfigLoader reads and validates the pipeline configuration from the pack.yaml file.
+
+### Actions
+
+kist supports plugin-based actions. Default actions include:
+
+- build: Compiles source files.
+- test: Runs tests.
+- lint: Lints the codebase.
+
+Custom actions can be implemented and registered as plugins.
+
+```mermaid
+graph TD
+    subgraph Pipeline
+        Stage1[Stage 1]
+        Stage2[Stage 2]
+        Stage3[Stage 3]
+    end
+
+    subgraph Stage1
+        Step1_1[Step 1.1]
+        Step1_2[Step 1.2]
+    end
+    subgraph Stage2
+        Step2_1[Step 2.1]
+        Step2_2[Step 2.2]
+    end
+    subgraph Stage3
+        Step3_1[Step 3.1]
+        Step3_2[Step 3.2]
+    end
+
+    Step1_1 --> Action1_1[Action: DirectoryCleanAction]
+    Step1_2 --> Action1_2[Action: DirectoryCopyAction]
+    Step2_1 --> Action2_1[Action: FileCopyAction]
+    Step2_2 --> Action2_2[Action: StyleProcessingAction]
+    Step3_1 --> Action3_1[Action: PackageManagerAction]
+    Step3_2 --> Action3_2[Action: VersionWriteAction]
+
+    Stage1 --> Stage2
+    Stage2 --> Stage3
+```
+
+---
+
+## Colophon
+
+### Authors
+
+**kist** is an open-source project by **[Scape Agency](https://www.scape.agency "Scape Agency website")**.
+
+#### Scape Agency
+
+Scape Agency is a spatial innovation collective that dreams, discovers and designs the everyday of tomorrow. We blend design thinking with emerging technologies to create a brighter perspective for people and planet. Our products and services naturalise technology in liveable and sustainable –scapes that spark the imagination and inspire future generations.
+
+- website: [scape.agency](https://www.scape.agency "Scape Agency website")
+- github: [github.com/getkist](https://github.com/getkist "Scape Agency GitHub")
+
+### Development Resources
+
+#### Contributing
+
+We'd love for you to contribute and to make this project even better than it is today!
+Please refer to the [contribution guidelines](.github/CONTRIBUTING.md) for information.
+
+Contributions are welcome! Follow these steps to contribute:
+
+1. Fork the repository.
+2. Create a new feature branch.
+3. Make your changes and write tests.
+4. Submit a pull request.
+
+### Legal Information
+
+#### Copyright
+
+Copyright &copy; 2024 [Scape Agency BV](https://www.scape.agency/ "Scape Agency website"). All Rights Reserved.
+
+#### License
+
+Except as otherwise noted, the code in this repository is licensed under the MIT License. Also see [LICENSE](https://github.com/getkist/community/blob/master/src/LICENSE). The documentation is licensed under the [Creative Commons Attribution 4.0 International (CC BY 4.0) License](https://creativecommons.org/licenses/by/4.0/).
+
+#### Disclaimer
+
+**THIS SOFTWARE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
+
+---
+
+<p align="center">
+    <b>Made with ❤️ by <a href="https://www.scape.agency" target="_blank">Scape Agency</a></b>
+</p>

package/js/actions/CoreActions.d.ts

@@ -0,0 +1,6 @@
+import { ActionInterface } from "../interface/ActionInterface";
+/**
+ * A record of core actions, mapped by their unique `name` property.
+ * Automatically derives names from the action classes.
+ */
+export declare const coreActions: Record<string, new () => ActionInterface>;

package/js/actions/CoreActions.js

@@ -0,0 +1,47 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coreActions = void 0;
+const DirectoryCleanAction_1 = require("../actions/DirectoryCleanAction");
+const DirectoryCopyAction_1 = require("../actions/DirectoryCopyAction");
+const DirectoryCreateAction_1 = require("../actions/DirectoryCreateAction");
+const DocumentationAction_1 = require("../actions/DocumentationAction");
+const FileCopyAction_1 = require("../actions/FileCopyAction");
+const FileRenameAction_1 = require("../actions/FileRenameAction");
+const JavaScriptMinifyAction_1 = require("../actions/JavaScriptMinifyAction");
+const LintAction_1 = require("../actions/LintAction");
+const PackageManagerAction_1 = require("../actions/PackageManagerAction");
+const StyleProcessingAction_1 = require("../actions/StyleProcessingAction");
+const SvgPackagerAction_1 = require("../actions/SvgPackagerAction");
+const SvgReaderAction_1 = require("../actions/SvgReaderAction");
+const SvgSpriteAction_1 = require("../actions/SvgSpriteAction");
+const SvgToPngAction_1 = require("../actions/SvgToPngAction");
+const TypeScriptCompilerAction_1 = require("../actions/TypeScriptCompilerAction");
+const VersionWriteAction_1 = require("../actions/VersionWriteAction");
+// ============================================================================
+// Core Actions
+// ============================================================================
+/**
+ * A record of core actions, mapped by their unique `name` property.
+ * Automatically derives names from the action classes.
+ */
+exports.coreActions = {
+    [new DirectoryCleanAction_1.DirectoryCleanAction().name]: DirectoryCleanAction_1.DirectoryCleanAction,
+    [new DirectoryCopyAction_1.DirectoryCopyAction().name]: DirectoryCopyAction_1.DirectoryCopyAction,
+    [new DirectoryCreateAction_1.DirectoryCreateAction().name]: DirectoryCreateAction_1.DirectoryCreateAction,
+    [new DocumentationAction_1.DocumentationAction().name]: DocumentationAction_1.DocumentationAction,
+    [new FileCopyAction_1.FileCopyAction().name]: FileCopyAction_1.FileCopyAction,
+    [new FileRenameAction_1.FileRenameAction().name]: FileRenameAction_1.FileRenameAction,
+    [new JavaScriptMinifyAction_1.JavaScriptMinifyAction().name]: JavaScriptMinifyAction_1.JavaScriptMinifyAction,
+    [new LintAction_1.LintAction().name]: LintAction_1.LintAction,
+    [new PackageManagerAction_1.PackageManagerAction().name]: PackageManagerAction_1.PackageManagerAction,
+    [new StyleProcessingAction_1.StyleProcessingAction().name]: StyleProcessingAction_1.StyleProcessingAction,
+    [new SvgPackagerAction_1.SvgPackagerAction().name]: SvgPackagerAction_1.SvgPackagerAction,
+    [new SvgReaderAction_1.SvgReaderAction().name]: SvgReaderAction_1.SvgReaderAction,
+    [new SvgSpriteAction_1.SvgSpriteAction().name]: SvgSpriteAction_1.SvgSpriteAction,
+    [new SvgToPngAction_1.SvgToPngAction().name]: SvgToPngAction_1.SvgToPngAction,
+    [new TypeScriptCompilerAction_1.TypeScriptCompilerAction().name]: TypeScriptCompilerAction_1.TypeScriptCompilerAction,
+    [new VersionWriteAction_1.VersionWriteAction().name]: VersionWriteAction_1.VersionWriteAction,
+};

package/js/actions/DirectoryCleanAction/DirectoryCleanAction.d.ts

@@ -0,0 +1,36 @@
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+/**
+ * DirectoryCleanAction is a step action responsible for cleaning a directory
+ * by deleting all its contents while optionally retaining files and
+ * directories that match specified glob patterns.
+ */
+export declare class DirectoryCleanAction extends Action {
+    /**
+     * Executes the directory cleaning action.
+     *
+     * @param options - The options specific to directory cleaning, including
+     * the directory path and glob patterns to retain.
+     * @returns A Promise that resolves when the directory has been
+     * successfully cleaned, or silently resolves if the directory does not
+     * exist.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+    /**
+     * Deletes all contents of a specified directory, excluding files and
+     * directories that match specified glob patterns.
+     *
+     * @param dirPath - The path to the directory to be cleaned.
+     * @param keepPatterns - An optional array of glob patterns for files
+     * and directories to retain.
+     * @returns A Promise that resolves when the directory has been
+     * successfully cleaned.
+     * @throws {Error} Throws an error if deleting any file or directory fails.
+     */
+    private cleanDirectoryContents;
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string;
+}

package/js/actions/DirectoryCleanAction/DirectoryCleanAction.js

@@ -0,0 +1,123 @@
+"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.DirectoryCleanAction = void 0;
+const fs_1 = __importDefault(require("fs"));
+const micromatch_1 = __importDefault(require("micromatch")); // For glob pattern matching
+const path_1 = __importDefault(require("path"));
+const Action_1 = require("../../core/pipeline/Action");
+// ============================================================================
+// Classes
+// ============================================================================
+/**
+ * DirectoryCleanAction is a step action responsible for cleaning a directory
+ * by deleting all its contents while optionally retaining files and
+ * directories that match specified glob patterns.
+ */
+class DirectoryCleanAction extends Action_1.Action {
+    // Methods
+    // ========================================================================
+    /**
+     * Executes the directory cleaning action.
+     *
+     * @param options - The options specific to directory cleaning, including
+     * the directory path and glob patterns to retain.
+     * @returns A Promise that resolves when the directory has been
+     * successfully cleaned, or silently resolves if the directory does not
+     * exist.
+     */
+    execute(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const dirPath = options.dirPath;
+            const keepPatterns = options.keep;
+            if (!dirPath) {
+                throw new Error("Missing required option: dirPath.");
+            }
+            if (!fs_1.default.existsSync(dirPath)) {
+                this.logWarn(`Directory does not exist, skipping: ${dirPath}`);
+                return; // Exit gracefully if directory does not exist
+            }
+            this.logInfo(`Cleaning directory: ${dirPath}`);
+            try {
+                yield this.cleanDirectoryContents(dirPath, keepPatterns);
+                this.logInfo(`Directory cleaned successfully: ${dirPath}`);
+            }
+            catch (error) {
+                this.logError(`Error cleaning directory "${dirPath}":`, error);
+            }
+        });
+    }
+    /**
+     * Deletes all contents of a specified directory, excluding files and
+     * directories that match specified glob patterns.
+     *
+     * @param dirPath - The path to the directory to be cleaned.
+     * @param keepPatterns - An optional array of glob patterns for files
+     * and directories to retain.
+     * @returns A Promise that resolves when the directory has been
+     * successfully cleaned.
+     * @throws {Error} Throws an error if deleting any file or directory fails.
+     */
+    cleanDirectoryContents(dirPath, keepPatterns) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const files = yield fs_1.default.promises.readdir(dirPath);
+            for (const file of files) {
+                const curPath = path_1.default.join(dirPath, file);
+                const relativePath = path_1.default.relative(dirPath, curPath);
+                // Skip files/directories matching keep patterns
+                if (keepPatterns &&
+                    micromatch_1.default.isMatch(relativePath, keepPatterns)) {
+                    this.logInfo(`Skipping: ${relativePath}`);
+                    continue;
+                }
+                try {
+                    const stat = yield fs_1.default.promises.lstat(curPath);
+                    if (stat.isDirectory()) {
+                        // Recursively clean subdirectory
+                        yield fs_1.default.promises.rmdir(curPath, { recursive: true });
+                        this.logInfo(`Deleted directory: ${relativePath}`);
+                    }
+                    else {
+                        // Delete file
+                        yield fs_1.default.promises.unlink(curPath);
+                        this.logInfo(`Deleted file: ${relativePath}`);
+                    }
+                }
+                catch (error) {
+                    this.logError(`Error deleting: ${relativePath}`, error);
+                }
+            }
+        });
+    }
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe() {
+        let description = `
+            Cleans a directory by deleting all its contents while retaining
+            files and directories matching specified glob patterns. If the
+            directory does not exist, the action will skip gracefully.
+        `;
+        return description;
+    }
+}
+exports.DirectoryCleanAction = DirectoryCleanAction;
+// ============================================================================
+// Export
+// ============================================================================
+// export default DirectoryCleanAction;

package/js/actions/DirectoryCleanAction/index.d.ts

@@ -0,0 +1,2 @@
+import { DirectoryCleanAction } from "./DirectoryCleanAction";
+export { DirectoryCleanAction };

package/js/actions/DirectoryCleanAction/index.js

@@ -0,0 +1,8 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirectoryCleanAction = void 0;
+const DirectoryCleanAction_1 = require("./DirectoryCleanAction");
+Object.defineProperty(exports, "DirectoryCleanAction", { enumerable: true, get: function () { return DirectoryCleanAction_1.DirectoryCleanAction; } });

package/js/actions/DirectoryCopyAction/DirectoryCopyAction.d.ts

@@ -0,0 +1,42 @@
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types";
+/**
+ * DirectoryCopyAction is a step action responsible for copying all files and
+ * subdirectories from one directory to another, using asynchronous operations
+ * for efficient handling.
+ */
+export declare class DirectoryCopyAction extends Action {
+    /**
+     * Executes the directory copy action.
+     * @param options - The options specific to directory copying, including
+     * the source and destination paths.
+     * @returns A Promise that resolves when the directory contents have been
+     * successfully copied, or rejects with an error if the action fails.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+    /**
+     * Asynchronously copies all files and subdirectories from the source
+     * directory to the destination directory. If the destination directory
+     * does not exist, it will be created.
+     *
+     * @param srcDir - The path of the source directory.
+     * @param destDir - The path of the destination directory.
+     * @throws {Error} If any file or directory could not be copied.
+     */
+    private copyFiles;
+    /**
+     * Recursively copies files and directories from the source to the
+     * destination directory.
+     * This method creates the destination directory if it does not exist and
+     * recursively copies all nested files and directories.
+     *
+     * @param srcDir - Source directory.
+     * @param destDir - Destination directory.
+     */
+    private recursiveCopy;
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string;
+}