kist 0.0.0 → 0.1.31

package/js/actions/DirectoryCopyAction/DirectoryCopyAction.js

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

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

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

package/js/actions/DirectoryCopyAction/index.js

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

package/js/actions/DirectoryCreateAction/DirectoryCreateAction.d.ts

@@ -0,0 +1,30 @@
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+/**
+ * DirectoryCreatorAction ensures that specified directory structures
+ * exist within a base path. It creates missing directories recursively.
+ */
+export declare 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.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+    /**
+     * 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 createDirectories;
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string;
+}

package/js/actions/DirectoryCreateAction/DirectoryCreateAction.js

@@ -0,0 +1,85 @@
+"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.DirectoryCreateAction = void 0;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const Action_1 = require("../../core/pipeline/Action");
+// ============================================================================
+// Classes
+// ============================================================================
+/**
+ * DirectoryCreatorAction ensures that specified directory structures
+ * exist within a base path. It creates missing directories recursively.
+ */
+class DirectoryCreateAction extends Action_1.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.
+     */
+    execute(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            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 {
+                yield 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.
+     */
+    createDirectories(basePath, directories) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const dir of directories) {
+                const dirPath = path_1.default.join(basePath, dir);
+                try {
+                    yield fs_1.promises.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() {
+        return "Creates specified directory structures under a given base path.";
+    }
+}
+exports.DirectoryCreateAction = DirectoryCreateAction;

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

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

package/js/actions/DirectoryCreateAction/index.js

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

package/js/actions/DocumentationAction/DocumentationAction.d.ts

@@ -0,0 +1,23 @@
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+/**
+ * DocumentationAction automates the generation of documentation for software
+ * projects. This action allows specifying a documentation generator, source
+ * paths, and output locations.
+ */
+export declare 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.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string;
+}

package/js/actions/DocumentationAction/DocumentationAction.js

@@ -0,0 +1,88 @@
+"use strict";
+// ============================================================================
+// Imports
+// ============================================================================
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentationAction = void 0;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const util_1 = __importDefault(require("util"));
+const Action_1 = require("../../core/pipeline/Action");
+// ============================================================================
+// Constants
+// ============================================================================
+const execFileAsync = util_1.default.promisify(child_process_1.execFile);
+// ============================================================================
+// Classes
+// ============================================================================
+/**
+ * DocumentationAction automates the generation of documentation for software
+ * projects. This action allows specifying a documentation generator, source
+ * paths, and output locations.
+ */
+class DocumentationAction extends Action_1.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.
+     */
+    execute(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { generatorCommand = "jsdoc", sourcePath = "./src", outputPath = "./docs", configPath = "", } = options;
+            if (!generatorCommand) {
+                throw new Error("Invalid options: 'generatorCommand' must be specified.");
+            }
+            const resolvedSourcePath = path_1.default.resolve(sourcePath);
+            const resolvedOutputPath = path_1.default.resolve(outputPath);
+            const resolvedConfigPath = configPath
+                ? path_1.default.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 } = yield 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) {
+                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() {
+        return "Generates project documentation using a specified tool (e.g., JSDoc, TypeDoc).";
+    }
+}
+exports.DocumentationAction = DocumentationAction;

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

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

package/js/actions/DocumentationAction/index.js

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

package/js/actions/FileCopyAction/FileCopyAction.d.ts

@@ -0,0 +1,42 @@
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+/**
+ * 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 declare class FileCopyAction extends Action {
+    /**
+     * 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.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+    /**
+     * 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 copyFileToDirectory;
+    /**
+     * Ensures that the given directory exists, creating it if it does not.
+     * @param dirPath - The path of the directory to check and create.
+     */
+    private ensureDirectoryExists;
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string;
+}

package/js/actions/FileCopyAction/FileCopyAction.js

@@ -0,0 +1,127 @@
+"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.FileCopyAction = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const Action_1 = require("../../core/pipeline/Action");
+// ============================================================================
+// 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.
+ */
+class FileCopyAction extends Action_1.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.
+     */
+    execute(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const srcFile = options.srcFile;
+            const destDir = options.destDir;
+            if (!srcFile || !destDir) {
+                throw new Error("Missing required options: srcFile or destDir.");
+            }
+            this.logInfo(`Copying file from ${srcFile} to ${destDir}.`);
+            try {
+                yield 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.
+     */
+    copyFileToDirectory(srcFile, destDir) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // Ensure the destination directory exists
+                yield this.ensureDirectoryExists(destDir);
+                // Resolve the destination file path
+                const fileName = path_1.default.basename(srcFile);
+                const destFilePath = path_1.default.join(destDir, fileName);
+                // Copy the file
+                yield fs_1.default.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.
+     */
+    ensureDirectoryExists(dirPath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield fs_1.default.promises.mkdir(dirPath, { recursive: true });
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    const nodeError = error;
+                    if (nodeError.code !== "EEXIST") {
+                        throw nodeError;
+                    }
+                }
+                else {
+                    throw error;
+                }
+            }
+        });
+    }
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe() {
+        return "Copies a file from a source location to a destination directory, ensuring directories exist and handling errors gracefully.";
+    }
+}
+exports.FileCopyAction = FileCopyAction;
+// ============================================================================
+// Export
+// ============================================================================
+// export default FileCopyAction;

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

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

package/js/actions/FileCopyAction/index.js

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

package/js/actions/FileRenameAction/FileRenameAction.d.ts

@@ -0,0 +1,30 @@
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+/**
+ * FileRenameAction handles renaming files within the file system.
+ * Ensures that file renaming operations are handled efficiently and safely.
+ */
+export declare 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.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+    /**
+     * 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 renameFile;
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string;
+}