kist 0.0.0 → 0.1.31

package/ts/actions/DirectoryCreateAction/DirectoryCreateAction.ts

@@ -0,0 +1,81 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { promises as fsPromises } from "fs";
+import path from "path";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * DirectoryCreatorAction ensures that specified directory structures
+ * exist within a base path. It creates missing directories recursively.
+ */
+export class DirectoryCreateAction extends Action {
+    /**
+     * Executes the directory creation action.
+     *
+     * @param options - The options specifying the base directory and
+     * the list of directories to create.
+     * @returns A Promise that resolves when all directories are created.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const { basePath, directories } = options;
+
+        if (!basePath || !directories || !Array.isArray(directories)) {
+            throw new Error(
+                "Invalid options: 'basePath' (string) and 'directories' (array) are required.",
+            );
+        }
+
+        this.logInfo(
+            `Ensuring directory structure under base path: ${basePath}`,
+        );
+
+        try {
+            await this.createDirectories(basePath, directories);
+            this.logInfo(
+                "All specified directories have been created successfully.",
+            );
+        } catch (error) {
+            this.logError("Failed to create directories.", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Ensures that directories exist under the specified base path.
+     *
+     * @param basePath - The base directory where subdirectories should be created.
+     * @param directories - An array of relative paths for directories to create.
+     * @returns A Promise that resolves when all directories exist.
+     */
+    private async createDirectories(
+        basePath: string,
+        directories: string[],
+    ): Promise<void> {
+        for (const dir of directories) {
+            const dirPath = path.join(basePath, dir);
+            try {
+                await fsPromises.mkdir(dirPath, { recursive: true });
+                this.logDebug(`Directory ensured: ${dirPath}`);
+            } catch (error) {
+                this.logError(`Error creating directory: ${dirPath}`, error);
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Creates specified directory structures under a given base path.";
+    }
+}

package/ts/actions/DirectoryCreateAction/index.ts

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

package/ts/actions/DocumentationAction/DocumentationAction.ts

@@ -0,0 +1,100 @@
+// ============================================================================
+// Imports
+// ============================================================================
+
+import { execFile } from "child_process";
+import path from "path";
+import util from "util";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const execFileAsync = util.promisify(execFile);
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * DocumentationAction automates the generation of documentation for software
+ * projects. This action allows specifying a documentation generator, source
+ * paths, and output locations.
+ */
+export class DocumentationAction extends Action {
+    /**
+     * Executes the documentation generation process using the specified command-line tool.
+     *
+     * @param options - The options specifying the generator tool, source path, and output path.
+     * @returns A Promise that resolves when documentation generation completes successfully.
+     * @throws {Error} Throws an error if the documentation process fails.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const {
+            generatorCommand = "jsdoc",
+            sourcePath = "./src",
+            outputPath = "./docs",
+            configPath = "",
+        } = options;
+
+        if (!generatorCommand) {
+            throw new Error(
+                "Invalid options: 'generatorCommand' must be specified.",
+            );
+        }
+
+        const resolvedSourcePath = path.resolve(sourcePath);
+        const resolvedOutputPath = path.resolve(outputPath);
+        const resolvedConfigPath = configPath
+            ? path.resolve(configPath)
+            : null;
+
+        this.logInfo(`Generating documentation with ${generatorCommand}...`);
+        this.logDebug(`Source Path: ${resolvedSourcePath}`);
+        this.logDebug(`Output Path: ${resolvedOutputPath}`);
+        if (resolvedConfigPath)
+            this.logDebug(`Config Path: ${resolvedConfigPath}`);
+
+        try {
+            // Construct command arguments
+            const args = resolvedConfigPath
+                ? ["-c", resolvedConfigPath, "-d", resolvedOutputPath]
+                : [resolvedSourcePath, "-d", resolvedOutputPath];
+
+            // Execute documentation generation command safely
+            const { stdout, stderr } = await execFileAsync(
+                generatorCommand,
+                args,
+            );
+
+            if (stderr) {
+                this.logError(`Documentation generation failed: ${stderr}`);
+                throw new Error(stderr);
+            }
+
+            this.logInfo(stdout);
+            this.logInfo(
+                `Documentation successfully generated at: ${resolvedOutputPath}`,
+            );
+        } catch (error: any) {
+            this.logError(
+                "Error occurred while generating documentation.",
+                error,
+            );
+            throw new Error(
+                `Documentation generation failed: ${error.message}`,
+            );
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Generates project documentation using a specified tool (e.g., JSDoc, TypeDoc).";
+    }
+}

package/ts/actions/DocumentationAction/index.ts

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

package/ts/actions/FileCopyAction/FileCopyAction.ts

@@ -0,0 +1,125 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import fs from "fs";
+import path from "path";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * FileCopyAction is a step action responsible for copying files from a source
+ * location to a destination directory. This action handles file path
+ * resolution and ensures that existing files in the destination can be
+ * replaced if necessary.
+ */
+export class FileCopyAction extends Action {
+    // Parameters
+    // ========================================================================
+
+    // Constructor
+    // ========================================================================
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Executes the file copy action.
+     * @param options - The options specific to file copying, including source
+     * file and destination directory.
+     * @returns A Promise that resolves when the file has been successfully
+     * copied, or rejects with an error if the action fails.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const srcFile = options.srcFile as string;
+        const destDir = options.destDir as string;
+
+        if (!srcFile || !destDir) {
+            throw new Error("Missing required options: srcFile or destDir.");
+        }
+
+        this.logInfo(`Copying file from ${srcFile} to ${destDir}.`);
+
+        try {
+            await this.copyFileToDirectory(srcFile, destDir);
+            this.logInfo(
+                `File copied successfully from ${srcFile} to ${destDir}.`,
+            );
+        } catch (error) {
+            this.logError(
+                `Error copying file from ${srcFile} to ${destDir}: ${error}`,
+            );
+            throw error;
+        }
+    }
+
+    /**
+     * Copies a file from a specified source to a destination directory.
+     * Handles file path resolution and ensures the destination directory
+     * exists.
+     *
+     * @param srcFile - The path of the source file to be copied.
+     * @param destDir - The destination directory where the file should
+     * be placed.
+     * @returns A Promise that resolves when the file has been successfully
+     * copied.
+     * @throws {Error} If the file cannot be copied, including due to
+     * permission errors or the source file not existing.
+     */
+    private async copyFileToDirectory(
+        srcFile: string,
+        destDir: string,
+    ): Promise<void> {
+        try {
+            // Ensure the destination directory exists
+            await this.ensureDirectoryExists(destDir);
+
+            // Resolve the destination file path
+            const fileName = path.basename(srcFile);
+            const destFilePath = path.join(destDir, fileName);
+
+            // Copy the file
+            await fs.promises.copyFile(srcFile, destFilePath);
+        } catch (error) {
+            this.logError(`Error copying file: ${error}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Ensures that the given directory exists, creating it if it does not.
+     * @param dirPath - The path of the directory to check and create.
+     */
+    private async ensureDirectoryExists(dirPath: string): Promise<void> {
+        try {
+            await fs.promises.mkdir(dirPath, { recursive: true });
+        } catch (error) {
+            if (error instanceof Error) {
+                const nodeError = error as NodeJS.ErrnoException;
+                if (nodeError.code !== "EEXIST") {
+                    throw nodeError;
+                }
+            } else {
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Copies a file from a source location to a destination directory, ensuring directories exist and handling errors gracefully.";
+    }
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+// export default FileCopyAction;

package/ts/actions/FileCopyAction/index.ts

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

package/ts/actions/FileRenameAction/FileRenameAction.ts

@@ -0,0 +1,82 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { promises as fsPromises } from "fs";
+import path from "path";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * FileRenameAction handles renaming files within the file system.
+ * Ensures that file renaming operations are handled efficiently and safely.
+ */
+export class FileRenameAction extends Action {
+    /**
+     * Executes the file renaming action.
+     *
+     * @param options - The options specifying the source and target file paths.
+     * @returns A Promise that resolves when the file has been successfully renamed.
+     * @throws {Error} If the source file does not exist or cannot be renamed.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const { srcPath, targetPath } = options;
+
+        if (!srcPath || !targetPath) {
+            throw new Error(
+                "Invalid options: 'srcPath' and 'targetPath' are required.",
+            );
+        }
+
+        this.logInfo(`Renaming file: ${srcPath} → ${targetPath}`);
+
+        try {
+            await this.renameFile(srcPath, targetPath);
+            this.logInfo(`File successfully renamed to ${targetPath}`);
+        } catch (error) {
+            this.logError("Failed to rename file.", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Renames a file from its current path to a new path.
+     *
+     * @param srcPath - The current file path.
+     * @param targetPath - The new file path.
+     * @returns A Promise that resolves once the file is successfully renamed.
+     */
+    private async renameFile(
+        srcPath: string,
+        targetPath: string,
+    ): Promise<void> {
+        try {
+            const resolvedSrcPath = path.resolve(srcPath);
+            const resolvedTargetPath = path.resolve(targetPath);
+
+            await fsPromises.rename(resolvedSrcPath, resolvedTargetPath);
+            this.logDebug(
+                `File renamed: ${resolvedSrcPath} → ${resolvedTargetPath}`,
+            );
+        } catch (error) {
+            this.logError(
+                `Error renaming file: ${srcPath} → ${targetPath}`,
+                error,
+            );
+            throw error;
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Renames a file from a specified source path to a target path.";
+    }
+}

package/ts/actions/FileRenameAction/index.ts

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

package/ts/actions/JavaScriptMinifyAction/JavaScriptMinifyAction.ts

@@ -0,0 +1,109 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { promises as fs } from "fs";
+import path from "path";
+import { minify, MinifyOptions } from "terser";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+import terserConfig from "./terser.config.js";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * JavaScriptMinifyAction handles the minification of JavaScript files.
+ * Uses Terser to reduce file size and optimize performance.
+ */
+export class JavaScriptMinifyAction extends Action {
+    /**
+     * Executes the JavaScript minification action.
+     *
+     * @param options - The options containing input and output file paths.
+     * @returns A Promise that resolves when the minification process completes.
+     * @throws {Error} If input file is missing, minification fails, or output cannot be written.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const { inputPath, outputPath, customConfig = {} } = options;
+
+        if (!inputPath || !outputPath) {
+            throw new Error(
+                "Invalid options: 'inputPath' and 'outputPath' are required.",
+            );
+        }
+
+        this.logInfo(
+            `Minifying JavaScript file: ${inputPath} → ${outputPath}`,
+        );
+
+        try {
+            await this.minifyFile(inputPath, outputPath, customConfig);
+            this.logInfo(`JavaScript minification completed: ${outputPath}`);
+        } catch (error) {
+            this.logError("JavaScript minification failed.", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Minifies a JavaScript file using Terser.
+     *
+     * @param inputPath - Path to the input JavaScript file.
+     * @param outputPath - Path where the minified file will be saved.
+     * @param customConfig - Custom Terser configuration.
+     * @returns A Promise that resolves when the minification is complete.
+     */
+
+    private async minifyFile(
+        inputPath: string,
+        outputPath: string,
+        customConfig: Record<string, any>,
+    ): Promise<void> {
+        try {
+            const resolvedInputPath = path.resolve(inputPath);
+            const resolvedOutputPath = path.resolve(outputPath);
+
+            // Read JavaScript file
+            const inputCode = await fs.readFile(resolvedInputPath, "utf8");
+
+            // Merge Terser configuration with explicit type casting
+            const terserOptions: MinifyOptions = {
+                ...terserConfig,
+                ...customConfig,
+                ecma: terserConfig.ecma as MinifyOptions["ecma"], // Ensure ecma is correctly typed
+                nameCache: terserConfig.nameCache ?? undefined, // Ensure nameCache is undefined if null
+            };
+
+            // Minify using Terser
+            const result = await minify(inputCode, terserOptions);
+
+            if (!result.code) {
+                throw new Error("Minification resulted in empty output.");
+            }
+
+            // Write minified file
+            await fs.writeFile(resolvedOutputPath, result.code, "utf8");
+
+            this.logDebug(
+                `Minified JavaScript file saved to ${resolvedOutputPath}`,
+            );
+        } catch (error) {
+            this.logError(
+                `Error minifying JavaScript file: ${inputPath}`,
+                error,
+            );
+            throw error;
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Minifies JavaScript files using Terser to reduce size and optimize performance.";
+    }
+}

package/ts/actions/JavaScriptMinifyAction/index.ts

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