kist 0.1.31 → 0.1.32

package/js/actions/CoreActions.js

@@ -13,11 +13,13 @@ 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 RunScriptAction_1 = require("../actions/RunScriptAction");
 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 TemplateRenderAction_1 = require("../actions/TemplateRenderAction");
 const TypeScriptCompilerAction_1 = require("../actions/TypeScriptCompilerAction");
 const VersionWriteAction_1 = require("../actions/VersionWriteAction");
 // ============================================================================
@@ -37,11 +39,13 @@ exports.coreActions = {
     [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 RunScriptAction_1.RunScriptAction().name]: RunScriptAction_1.RunScriptAction,
     [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 TemplateRenderAction_1.TemplateRenderAction().name]: TemplateRenderAction_1.TemplateRenderAction,
     [new TypeScriptCompilerAction_1.TypeScriptCompilerAction().name]: TypeScriptCompilerAction_1.TypeScriptCompilerAction,
     [new VersionWriteAction_1.VersionWriteAction().name]: VersionWriteAction_1.VersionWriteAction,
 };

package/js/actions/RunScriptAction/RunScriptAction.d.ts

@@ -0,0 +1,22 @@
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+/**
+ * RunScriptAction executes an external JavaScript file as part of a KIST pipeline.
+ * The script is executed in a separate process to avoid blocking the main application.
+ */
+export declare class RunScriptAction extends Action {
+    /**
+     * Executes the external script file.
+     *
+     * @param options - The options specifying the script file to execute.
+     * @returns A Promise that resolves when the script execution completes.
+     * @throws {Error} If the script execution fails.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string;
+}

package/js/actions/RunScriptAction/RunScriptAction.js

@@ -0,0 +1,77 @@
+"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.RunScriptAction = 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
+// ============================================================================
+/**
+ * RunScriptAction executes an external JavaScript file as part of a KIST pipeline.
+ * The script is executed in a separate process to avoid blocking the main application.
+ */
+class RunScriptAction extends Action_1.Action {
+    /**
+     * Executes the external script file.
+     *
+     * @param options - The options specifying the script file to execute.
+     * @returns A Promise that resolves when the script execution completes.
+     * @throws {Error} If the script execution fails.
+     */
+    execute(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { scriptPath, args = [] } = options;
+            if (!scriptPath) {
+                throw new Error("Invalid options: 'scriptPath' is required.");
+            }
+            const resolvedScriptPath = path_1.default.resolve(scriptPath);
+            this.logInfo(`Executing external script: ${resolvedScriptPath}...`);
+            try {
+                const { stdout, stderr } = yield execFileAsync("node", [
+                    resolvedScriptPath,
+                    ...args,
+                ]);
+                if (stderr) {
+                    this.logError(`Script execution failed: ${stderr}`);
+                    throw new Error(stderr);
+                }
+                this.logInfo(stdout);
+                this.logInfo("Script executed successfully.");
+            }
+            catch (error) {
+                this.logError("Error occurred while executing the script.", error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe() {
+        return "Executes an external JavaScript file as part of the KIST pipeline.";
+    }
+}
+exports.RunScriptAction = RunScriptAction;

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

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

package/js/actions/RunScriptAction/index.js

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

package/js/actions/TemplateRenderAction/TemplateRenderAction.d.ts

@@ -0,0 +1,25 @@
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+/**
+ * TemplateRenderAction is responsible for rendering and writing multiple files
+ * from Nunjucks templates in a single action. It allows batch generation of
+ * output files based on a shared template context.
+ */
+export declare class TemplateRenderAction extends Action {
+    /**
+     * Executes the template rendering process for multiple templates.
+     *
+     * @param options - The options specifying the template directory,
+     * template-output mapping, and rendering context.
+     * @returns A Promise that resolves when all templates have been rendered.
+     * @throws {Error} Throws an error if template processing fails.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string;
+}
+export default TemplateRenderAction;

package/js/actions/TemplateRenderAction/TemplateRenderAction.js

@@ -0,0 +1,91 @@
+"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.TemplateRenderAction = void 0;
+const promises_1 = require("fs/promises");
+const nunjucks_1 = __importDefault(require("nunjucks"));
+const path_1 = __importDefault(require("path"));
+const Action_1 = require("../../core/pipeline/Action");
+const nunjucks_config_js_1 = __importDefault(require("./nunjucks.config.js"));
+// ============================================================================
+// Classes
+// ============================================================================
+/**
+ * TemplateRenderAction is responsible for rendering and writing multiple files
+ * from Nunjucks templates in a single action. It allows batch generation of
+ * output files based on a shared template context.
+ */
+class TemplateRenderAction extends Action_1.Action {
+    /**
+     * Executes the template rendering process for multiple templates.
+     *
+     * @param options - The options specifying the template directory,
+     * template-output mapping, and rendering context.
+     * @returns A Promise that resolves when all templates have been rendered.
+     * @throws {Error} Throws an error if template processing fails.
+     */
+    execute(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { templatesDir = "./templates", templates = [], context = {}, customConfig = {}, } = options;
+            if (!Array.isArray(templates) || templates.length === 0) {
+                throw new Error("Invalid options: 'templates' must be an array containing template-output pairs.");
+            }
+            this.logInfo(`Rendering ${templates.length} templates...`);
+            try {
+                // Merge Nunjucks configurations
+                const config = Object.assign(Object.assign({}, nunjucks_config_js_1.default), customConfig);
+                nunjucks_1.default.configure(templatesDir, config);
+                // Render each template and save to its corresponding output path
+                for (const { template, outputFile } of templates) {
+                    if (!template || !outputFile) {
+                        throw new Error(`Invalid template entry: ${JSON.stringify({
+                            template,
+                            outputFile,
+                        })}`);
+                    }
+                    this.logInfo(`Rendering: ${template} → ${outputFile}`);
+                    // Render template content
+                    const content = nunjucks_1.default.render(template, context);
+                    // Ensure the output directory exists
+                    const dir = path_1.default.dirname(outputFile);
+                    yield (0, promises_1.mkdir)(dir, { recursive: true });
+                    // Write the rendered template to file
+                    yield (0, promises_1.writeFile)(outputFile, content, "utf-8");
+                    this.logInfo(`✓ Successfully rendered: ${outputFile}`);
+                }
+                this.logInfo("All templates rendered successfully.");
+            }
+            catch (error) {
+                this.logError("Error rendering templates.", error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe() {
+        return "Renders multiple Nunjucks templates into files using a shared context.";
+    }
+}
+exports.TemplateRenderAction = TemplateRenderAction;
+// ============================================================================
+// Export
+// ============================================================================
+exports.default = TemplateRenderAction;

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

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

package/js/actions/TemplateRenderAction/index.js

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

package/js/actions/TemplateRenderAction/nunjucks.config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Configuration options for Nunjucks to ensure safe and efficient template rendering.
+ * This setup is ideal for both development and production environments, providing a balance
+ * between performance optimizations and security best practices.
+ */
+declare const nunjucksConfig: {
+    autoescape: boolean;
+    throwOnUndefined: boolean;
+    trimBlocks: boolean;
+    lstripBlocks: boolean;
+    noCache: boolean;
+};
+export default nunjucksConfig;

package/js/actions/TemplateRenderAction/nunjucks.config.js

@@ -0,0 +1,23 @@
+"use strict";
+// This configuration is tailored to a typical web application setup. Adjust the `noCache` option
+// according to your caching strategy for production environments to optimize performance.
+Object.defineProperty(exports, "__esModule", { value: true });
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Configuration options for Nunjucks to ensure safe and efficient template rendering.
+ * This setup is ideal for both development and production environments, providing a balance
+ * between performance optimizations and security best practices.
+ */
+const nunjucksConfig = {
+    autoescape: true, // Controls if output with dangerous characters are escaped automatically
+    throwOnUndefined: false, // Throw errors when outputting a null/undefined value
+    trimBlocks: true, // Automatically remove trailing newlines from a block/tag
+    lstripBlocks: true, // Automatically remove leading whitespace from a block/tag
+    noCache: true,
+};
+// ============================================================================
+// Export
+// ============================================================================
+exports.default = nunjucksConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kist",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "Package Pipeline Processor",
   "keywords": [
     "kist",

package/ts/actions/CoreActions.ts

@@ -15,6 +15,7 @@ import { JavaScriptMinifyAction } from "../actions/JavaScriptMinifyAction";
 import { LintAction } from "../actions/LintAction";
 
 import { PackageManagerAction } from "../actions/PackageManagerAction";
+import { RunScriptAction } from "../actions/RunScriptAction";
 
 import { StyleProcessingAction } from "../actions/StyleProcessingAction";
 
@@ -23,6 +24,7 @@ import { SvgReaderAction } from "../actions/SvgReaderAction";
 import { SvgSpriteAction } from "../actions/SvgSpriteAction";
 import { SvgToPngAction } from "../actions/SvgToPngAction";
 
+import { TemplateRenderAction } from "../actions/TemplateRenderAction";
 import { TypeScriptCompilerAction } from "../actions/TypeScriptCompilerAction";
 
 import { VersionWriteAction } from "../actions/VersionWriteAction";
@@ -51,6 +53,7 @@ export const coreActions: Record<string, new () => ActionInterface> = {
     [new LintAction().name]: LintAction,
 
     [new PackageManagerAction().name]: PackageManagerAction,
+    [new RunScriptAction().name]: RunScriptAction,
     [new StyleProcessingAction().name]: StyleProcessingAction,
 
     [new SvgPackagerAction().name]: SvgPackagerAction,
@@ -58,6 +61,7 @@ export const coreActions: Record<string, new () => ActionInterface> = {
     [new SvgSpriteAction().name]: SvgSpriteAction,
     [new SvgToPngAction().name]: SvgToPngAction,
 
+    [new TemplateRenderAction().name]: TemplateRenderAction,
     [new TypeScriptCompilerAction().name]: TypeScriptCompilerAction,
 
     [new VersionWriteAction().name]: VersionWriteAction,

package/ts/actions/RunScriptAction/RunScriptAction.ts

@@ -0,0 +1,71 @@
+// ============================================================================
+// 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
+// ============================================================================
+
+/**
+ * RunScriptAction executes an external JavaScript file as part of a KIST pipeline.
+ * The script is executed in a separate process to avoid blocking the main application.
+ */
+export class RunScriptAction extends Action {
+    /**
+     * Executes the external script file.
+     *
+     * @param options - The options specifying the script file to execute.
+     * @returns A Promise that resolves when the script execution completes.
+     * @throws {Error} If the script execution fails.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const { scriptPath, args = [] } = options;
+
+        if (!scriptPath) {
+            throw new Error("Invalid options: 'scriptPath' is required.");
+        }
+
+        const resolvedScriptPath = path.resolve(scriptPath);
+
+        this.logInfo(`Executing external script: ${resolvedScriptPath}...`);
+
+        try {
+            const { stdout, stderr } = await execFileAsync("node", [
+                resolvedScriptPath,
+                ...args,
+            ]);
+
+            if (stderr) {
+                this.logError(`Script execution failed: ${stderr}`);
+                throw new Error(stderr);
+            }
+
+            this.logInfo(stdout);
+            this.logInfo("Script executed successfully.");
+        } catch (error) {
+            this.logError("Error occurred while executing the script.", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Executes an external JavaScript file as part of the KIST pipeline.";
+    }
+}

package/ts/actions/RunScriptAction/index.ts

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

package/ts/actions/TemplateRenderAction/TemplateRenderAction.ts

@@ -0,0 +1,98 @@
+// ============================================================================
+// Imports
+// ============================================================================
+
+import { mkdir, writeFile } from "fs/promises";
+import nunjucks from "nunjucks";
+import path from "path";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+import nunjucksConfig from "./nunjucks.config.js";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * TemplateRenderAction is responsible for rendering and writing multiple files
+ * from Nunjucks templates in a single action. It allows batch generation of
+ * output files based on a shared template context.
+ */
+export class TemplateRenderAction extends Action {
+    /**
+     * Executes the template rendering process for multiple templates.
+     *
+     * @param options - The options specifying the template directory,
+     * template-output mapping, and rendering context.
+     * @returns A Promise that resolves when all templates have been rendered.
+     * @throws {Error} Throws an error if template processing fails.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const {
+            templatesDir = "./templates",
+            templates = [],
+            context = {},
+            customConfig = {},
+        } = options;
+
+        if (!Array.isArray(templates) || templates.length === 0) {
+            throw new Error(
+                "Invalid options: 'templates' must be an array containing template-output pairs."
+            );
+        }
+
+        this.logInfo(`Rendering ${templates.length} templates...`);
+
+        try {
+            // Merge Nunjucks configurations
+            const config = { ...nunjucksConfig, ...customConfig };
+            nunjucks.configure(templatesDir, config);
+
+            // Render each template and save to its corresponding output path
+            for (const { template, outputFile } of templates) {
+                if (!template || !outputFile) {
+                    throw new Error(
+                        `Invalid template entry: ${JSON.stringify({
+                            template,
+                            outputFile,
+                        })}`
+                    );
+                }
+
+                this.logInfo(`Rendering: ${template} → ${outputFile}`);
+
+                // Render template content
+                const content = nunjucks.render(template, context);
+
+                // Ensure the output directory exists
+                const dir = path.dirname(outputFile);
+                await mkdir(dir, { recursive: true });
+
+                // Write the rendered template to file
+                await writeFile(outputFile, content, "utf-8");
+
+                this.logInfo(`✓ Successfully rendered: ${outputFile}`);
+            }
+
+            this.logInfo("All templates rendered successfully.");
+        } catch (error) {
+            this.logError("Error rendering templates.", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     *
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Renders multiple Nunjucks templates into files using a shared context.";
+    }
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export default TemplateRenderAction;

package/ts/actions/TemplateRenderAction/index.ts

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

package/ts/actions/TemplateRenderAction/nunjucks.config.ts

@@ -0,0 +1,32 @@
+// This configuration is tailored to a typical web application setup. Adjust the `noCache` option
+// according to your caching strategy for production environments to optimize performance.
+
+// ============================================================================
+// Import
+// ============================================================================
+
+// Importing path for potential future use in specifying template directories or other file paths
+import path from "node:path";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Configuration options for Nunjucks to ensure safe and efficient template rendering.
+ * This setup is ideal for both development and production environments, providing a balance
+ * between performance optimizations and security best practices.
+ */
+const nunjucksConfig = {
+    autoescape: true, // Controls if output with dangerous characters are escaped automatically
+    throwOnUndefined: false, // Throw errors when outputting a null/undefined value
+    trimBlocks: true, // Automatically remove trailing newlines from a block/tag
+    lstripBlocks: true, // Automatically remove leading whitespace from a block/tag
+    noCache: true,
+};
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export default nunjucksConfig;