kist 0.0.0 → 0.1.31

package/js/logger/Logger.js

@@ -0,0 +1,151 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const LoggerStyles_1 = require("./LoggerStyles");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * Logger class for handling console messages.
+ * Singleton instance ensures consistent logging behavior throughout the
+ * application.
+ */
+class Logger {
+    // Constructor
+    // ========================================================================
+    /**
+     * Private constructor to enforce singleton pattern.
+     * @param logLevel - The log level for controlling log output.
+     */
+    constructor(logLevel = "info") {
+        this.logLevel = logLevel;
+    }
+    // Singleton Methods
+    // ========================================================================
+    /**
+     * Retrieves the singleton instance of Logger.
+     * Initializes a non-verbose Logger instance if it hasn't been explicitly
+     * initialized.
+     *
+     * @returns The Logger instance.
+     */
+    static getInstance(logLevel = "info") {
+        if (!Logger.instance) {
+            // Default to "info" level if not initialized explicitly
+            Logger.instance = new Logger(logLevel);
+        }
+        return Logger.instance;
+    }
+    /**
+     * Resets the Logger instance.
+     * Useful for testing or reinitializing the Logger during runtime.
+     */
+    static resetInstance() {
+        Logger.instance = null;
+    }
+    // Logging Methods
+    // ========================================================================
+    /**
+     * Logs a message with a specific level if it meets the current log level.
+     *
+     * @param level - The log level (e.g., "INFO", "WARN", "ERROR").
+     * @param context - The context or class name where the log originates.
+     * @param message - The message content to log.
+     * @param fgStyle - The foreground color style to apply to the log level.
+     * @param bgStyle - The background color style to apply to the log level (default is reset).
+     */
+    log(level, context, message, fgStyle, bgStyle = LoggerStyles_1.LoggerStyles.Reset) {
+        if (this.shouldLog(level)) {
+            const formattedMessage = `${fgStyle}${bgStyle}[${level.toUpperCase()}]${LoggerStyles_1.LoggerStyles.Reset} [${LoggerStyles_1.LoggerStyles.Cyan}${context}${LoggerStyles_1.LoggerStyles.Reset}] ${message}`;
+            console[level === "error" ? "error" : level === "warn" ? "warn" : "log"](formattedMessage);
+        }
+    }
+    /**
+     * Determines if a log should be displayed based on the current log level.
+     *
+     * @param level - The level of the log being checked.
+     * @returns True if the log should be displayed, otherwise false.
+     */
+    shouldLog(level) {
+        const levels = ["debug", "info", "warn", "error"];
+        return levels.indexOf(level) >= levels.indexOf(this.logLevel);
+    }
+    /**
+     * Logs an informational message.
+     *
+     * @param context - The originating class or module.
+     * @param message - The informational message to log.
+     */
+    logInfo(context, message) {
+        this.log("info", context, message, LoggerStyles_1.LoggerStyles.Blue);
+    }
+    /**
+     * Logs a warning message.
+     *
+     * @param context - The originating class or module.
+     * @param message - The warning message to log.
+     */
+    logWarn(context, message) {
+        this.log("warn", context, message, LoggerStyles_1.LoggerStyles.Yellow);
+    }
+    /**
+     * Logs an error message.
+     *
+     * @param context - The originating class or module.
+     * @param message - The error message to log.
+     * @param error - (Optional) Additional error details.
+     */
+    logError(context, message, error) {
+        const formattedMessage = this.formatError(message, error);
+        this.log("error", context, formattedMessage, LoggerStyles_1.LoggerStyles.Red, LoggerStyles_1.LoggerStyles.BgYellow);
+    }
+    /**
+     * Logs a debug message.
+     *
+     * @param context - The originating class or module.
+     * @param message - The debug message to log.
+     */
+    logDebug(context, message) {
+        this.log("debug", context, message, LoggerStyles_1.LoggerStyles.Magenta);
+    }
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Sets the log level dynamically.
+     *
+     * @param level - The log level to set (e.g., "debug", "info").
+     */
+    setLogLevel(level) {
+        this.logLevel = level;
+    }
+    /**
+     * Formats an error message for logging.
+     * Combines a base 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;
+    }
+}
+exports.Logger = Logger;
+// Parameters
+// ========================================================================
+/**
+ * Singleton instance
+ */
+Logger.instance = null;

package/js/logger/LoggerStyles.d.ts

@@ -0,0 +1,23 @@
+/**
+ * LoggerStyles defines terminal color codes for text and background styling.
+ * These styles are used to format log messages with colors and effects.
+ */
+export declare enum LoggerStyles {
+    Reset = "\u001B[0m",
+    Bold = "\u001B[1m",
+    Dim = "\u001B[2m",
+    Red = "\u001B[31m",
+    Green = "\u001B[32m",
+    Yellow = "\u001B[33m",
+    Blue = "\u001B[34m",
+    Magenta = "\u001B[35m",
+    Cyan = "\u001B[36m",
+    Gray = "\u001B[90m",
+    BgRed = "\u001B[41m",
+    BgGreen = "\u001B[42m",
+    BgYellow = "\u001B[43m",
+    BgBlue = "\u001B[44m",
+    BgMagenta = "\u001B[45m",
+    BgCyan = "\u001B[46m",
+    BgGray = "\u001B[100m"
+}

package/js/logger/LoggerStyles.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggerStyles = void 0;
+/**
+ * LoggerStyles defines terminal color codes for text and background styling.
+ * These styles are used to format log messages with colors and effects.
+ */
+var LoggerStyles;
+(function (LoggerStyles) {
+    // Reset and Effects
+    LoggerStyles["Reset"] = "\u001B[0m";
+    LoggerStyles["Bold"] = "\u001B[1m";
+    LoggerStyles["Dim"] = "\u001B[2m";
+    // Foreground Colors
+    LoggerStyles["Red"] = "\u001B[31m";
+    LoggerStyles["Green"] = "\u001B[32m";
+    LoggerStyles["Yellow"] = "\u001B[33m";
+    LoggerStyles["Blue"] = "\u001B[34m";
+    LoggerStyles["Magenta"] = "\u001B[35m";
+    LoggerStyles["Cyan"] = "\u001B[36m";
+    LoggerStyles["Gray"] = "\u001B[90m";
+    // Background Colors
+    LoggerStyles["BgRed"] = "\u001B[41m";
+    LoggerStyles["BgGreen"] = "\u001B[42m";
+    LoggerStyles["BgYellow"] = "\u001B[43m";
+    LoggerStyles["BgBlue"] = "\u001B[44m";
+    LoggerStyles["BgMagenta"] = "\u001B[45m";
+    LoggerStyles["BgCyan"] = "\u001B[46m";
+    LoggerStyles["BgGray"] = "\u001B[100m";
+})(LoggerStyles || (exports.LoggerStyles = LoggerStyles = {}));

package/js/types/ActionOptionsType.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Defines the structure of options passed to step actions.
+ * This type provides a flexible, yet type-safe, way to manage action-specific settings.
+ */
+export interface ActionOptionsType {
+    [key: string]: any;
+    optionalField?: string;
+}

package/js/types/ActionOptionsType.js

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

package/js/types/index.d.ts

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

package/js/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/types/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,11 +1,97 @@
 {
   "name": "kist",
-  "version": "0.0.0",
+  "version": "0.1.31",
   "description": "Package Pipeline Processor",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "keywords": [
+    "kist",
+    "package",
+    "packager",
+    "build",
+    "builder",
+    "compile",
+    "compiler",
+    "framework",
+    "web"
+  ],
+  "license": "MIT",
+  "homepage": "https://www.getkist.com/",
+  "main": "js/index.js",
+  "types": "js/index.d.ts",
+  "files": [
+    "code-snippets/**/*.code-snippets",
+    "css/**/*.{css,map}",
+    "font/**/*.{eot,otf,ttf,woff,woff2}",
+    "inkscape/**/*.inkscape",
+    "jinja/**/*.jinja",
+    "js/**/*.d.ts",
+    "js/**/*.{js,map}",
+    "less/**/*.less",
+    "md/**/*.md",
+    "oco/**/*.oco",
+    "png/**/*.png",
+    "py/**/*.py",
+    "rcpx/**/*.rcpx",
+    "scss/**/*.scss",
+    "sketchpalette/**/*.sketchpalette",
+    "styl/**/*.styl",
+    "svg/**/*.svg",
+    "tex/**/*.tex",
+    "ts/**/*.ts",
+    "!.DS_Store"
+  ],
+  "author": "Lars van Vianen <lars@vianen.com> (https://vianen.com)",
+  "contributors": [
+    "Scape Agency <info@scape.agency>"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getkist/kist.git"
   },
-  "author": "",
-  "license": "ISC"
-}
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/scape-foundation"
+    }
+  ],
+  "bin": {
+    "kist": "js/cli.js"
+  },
+  "dependencies": {
+    "@babel/core": "^7.23.6",
+    "@babel/preset-env": "^7.23.6",
+    "@babel/preset-typescript": "^7.23.3",
+    "@types/fs-extra": "^11.0.4",
+    "@types/glob": "^8.1.0",
+    "@types/jsdom": "^21.1.6",
+    "@types/micromatch": "^4.0.9",
+    "@types/node": "^22.13.0",
+    "@types/nunjucks": "^3.2.6",
+    "@types/svg-sprite": "^0.0.39",
+    "autoprefixer": "^10.4.16",
+    "chokidar": "^4.0.0",
+    "cssnano": "^7.0.4",
+    "del": "^8.0.0",
+    "eslint": "^9.9.0",
+    "eslint-config-prettier": "^10.0.1",
+    "express": "^4.21.0",
+    "express-rate-limit": "^7.5.0",
+    "fantasticon": "^3.0.0",
+    "fs-extra": "^11.2.0",
+    "glob": "^11.0.0",
+    "js-yaml": "^4.1.0",
+    "jsdom": "^26.0.0",
+    "lodash": "^4.17.21",
+    "nunjucks": "^3.2.4",
+    "postcss": "^8.4.32",
+    "postcss-preset-env": "^10.0.0",
+    "prettier": "^3.0.3",
+    "sass": "^1.69.7",
+    "sassdoc": "^2.7.4",
+    "semver": "^7.5.4",
+    "sharp": "^0.33.1",
+    "svg-sprite": "^2.0.2",
+    "svgo": "^3.1.0",
+    "terser": "^5.26.0",
+    "ws": "^8.18.0"
+  }
+}

package/ts/actions/CoreActions.ts

@@ -0,0 +1,64 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { DirectoryCleanAction } from "../actions/DirectoryCleanAction";
+import { DirectoryCopyAction } from "../actions/DirectoryCopyAction";
+import { DirectoryCreateAction } from "../actions/DirectoryCreateAction";
+
+import { DocumentationAction } from "../actions/DocumentationAction";
+
+import { FileCopyAction } from "../actions/FileCopyAction";
+import { FileRenameAction } from "../actions/FileRenameAction";
+
+import { JavaScriptMinifyAction } from "../actions/JavaScriptMinifyAction";
+import { LintAction } from "../actions/LintAction";
+
+import { PackageManagerAction } from "../actions/PackageManagerAction";
+
+import { StyleProcessingAction } from "../actions/StyleProcessingAction";
+
+import { SvgPackagerAction } from "../actions/SvgPackagerAction";
+import { SvgReaderAction } from "../actions/SvgReaderAction";
+import { SvgSpriteAction } from "../actions/SvgSpriteAction";
+import { SvgToPngAction } from "../actions/SvgToPngAction";
+
+import { TypeScriptCompilerAction } from "../actions/TypeScriptCompilerAction";
+
+import { VersionWriteAction } from "../actions/VersionWriteAction";
+
+import { ActionInterface } from "../interface/ActionInterface";
+
+// ============================================================================
+// Core Actions
+// ============================================================================
+
+/**
+ * A record of core actions, mapped by their unique `name` property.
+ * Automatically derives names from the action classes.
+ */
+export const coreActions: Record<string, new () => ActionInterface> = {
+    [new DirectoryCleanAction().name]: DirectoryCleanAction,
+    [new DirectoryCopyAction().name]: DirectoryCopyAction,
+    [new DirectoryCreateAction().name]: DirectoryCreateAction,
+
+    [new DocumentationAction().name]: DocumentationAction,
+
+    [new FileCopyAction().name]: FileCopyAction,
+    [new FileRenameAction().name]: FileRenameAction,
+
+    [new JavaScriptMinifyAction().name]: JavaScriptMinifyAction,
+    [new LintAction().name]: LintAction,
+
+    [new PackageManagerAction().name]: PackageManagerAction,
+    [new StyleProcessingAction().name]: StyleProcessingAction,
+
+    [new SvgPackagerAction().name]: SvgPackagerAction,
+    [new SvgReaderAction().name]: SvgReaderAction,
+    [new SvgSpriteAction().name]: SvgSpriteAction,
+    [new SvgToPngAction().name]: SvgToPngAction,
+
+    [new TypeScriptCompilerAction().name]: TypeScriptCompilerAction,
+
+    [new VersionWriteAction().name]: VersionWriteAction,
+};

package/ts/actions/DirectoryCleanAction/DirectoryCleanAction.ts

@@ -0,0 +1,121 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import fs from "fs";
+import micromatch from "micromatch"; // For glob pattern matching
+import path from "path";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+
+// ============================================================================
+// 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.
+ */
+export class DirectoryCleanAction extends 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.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const dirPath = options.dirPath as string;
+        const keepPatterns = options.keep as string[] | undefined;
+
+        if (!dirPath) {
+            throw new Error("Missing required option: dirPath.");
+        }
+
+        if (!fs.existsSync(dirPath)) {
+            this.logWarn(`Directory does not exist, skipping: ${dirPath}`);
+            return; // Exit gracefully if directory does not exist
+        }
+
+        this.logInfo(`Cleaning directory: ${dirPath}`);
+
+        try {
+            await 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.
+     */
+    private async cleanDirectoryContents(
+        dirPath: string,
+        keepPatterns?: string[],
+    ): Promise<void> {
+        const files = await fs.promises.readdir(dirPath);
+
+        for (const file of files) {
+            const curPath = path.join(dirPath, file);
+            const relativePath = path.relative(dirPath, curPath);
+
+            // Skip files/directories matching keep patterns
+            if (
+                keepPatterns &&
+                micromatch.isMatch(relativePath, keepPatterns)
+            ) {
+                this.logInfo(`Skipping: ${relativePath}`);
+                continue;
+            }
+
+            try {
+                const stat = await fs.promises.lstat(curPath);
+                if (stat.isDirectory()) {
+                    // Recursively clean subdirectory
+                    await fs.promises.rmdir(curPath, { recursive: true });
+                    this.logInfo(`Deleted directory: ${relativePath}`);
+                } else {
+                    // Delete file
+                    await fs.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(): string {
+        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;
+    }
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+// export default DirectoryCleanAction;

package/ts/actions/DirectoryCleanAction/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { DirectoryCleanAction } from "./DirectoryCleanAction";
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export { DirectoryCleanAction };

package/ts/actions/DirectoryCopyAction/DirectoryCopyAction.ts

@@ -0,0 +1,118 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { promises as fs } from "fs";
+import path from "path";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * DirectoryCopyAction is a step action responsible for copying all files and
+ * subdirectories from one directory to another, using asynchronous operations
+ * for efficient handling.
+ */
+export class DirectoryCopyAction extends Action {
+    // Methods
+    // ========================================================================
+
+    /**
+     * 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.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const srcDir = options.srcDir as string;
+        const destDir = options.destDir as string;
+
+        if (!srcDir || !destDir) {
+            throw new Error("Missing required options: srcDir or destDir.");
+        }
+
+        this.logInfo(`Copying files from ${srcDir} to ${destDir}`);
+
+        try {
+            await this.copyFiles(srcDir, destDir);
+            this.logInfo(
+                `Files copied successfully from ${srcDir} to ${destDir}`,
+            );
+        } catch (error) {
+            this.logError(
+                `Error copying files from ${srcDir} to ${destDir}: ${error}`,
+            );
+            throw error;
+        }
+    }
+
+    /**
+     * 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 async copyFiles(srcDir: string, destDir: string): Promise<void> {
+        const resolvedSrcDir: string = path.resolve(srcDir);
+        const resolvedDestDir: string = path.resolve(destDir);
+
+        try {
+            await this.recursiveCopy(resolvedSrcDir, resolvedDestDir);
+        } catch (error) {
+            throw new Error(
+                `Failed to copy from ${resolvedSrcDir} to ${resolvedDestDir}: ${error}`,
+            );
+        }
+    }
+
+    /**
+     * 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 async recursiveCopy(
+        srcDir: string,
+        destDir: string,
+    ): Promise<void> {
+        await fs.mkdir(destDir, { recursive: true });
+        const entries = await fs.readdir(srcDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const srcPath = path.join(srcDir, entry.name);
+            const destPath = path.join(destDir, entry.name);
+
+            if (entry.isDirectory()) {
+                // Recursively copy subdirectory
+                await this.recursiveCopy(srcPath, destPath);
+            } else {
+                // Copy file
+                await fs.copyFile(srcPath, destPath);
+            }
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Copies all files and subdirectories from one directory to another, including handling of nested directories.";
+    }
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+// export default DirectoryCopyAction;

package/ts/actions/DirectoryCopyAction/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { DirectoryCopyAction } from "./DirectoryCopyAction";
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export { DirectoryCopyAction };