kist 0.1.45 → 0.1.58

package/ts/config/actions.config.ts

@@ -0,0 +1,137 @@
+// ============================================================================
+// Core Actions Configuration
+// ============================================================================
+
+/**
+ * Defines which actions are considered "core" and will remain in the main
+ * kist package. All other actions should be moved to separate plugin packages.
+ *
+ * Core Actions (Lightweight essentials):
+ * - Directory operations (create, copy, clean)
+ * - File operations (copy, rename)
+ * - Version management
+ * - Template rendering (lightweight)
+ *
+ * Plugin Actions (Move to separate repos):
+ * - StyleProcessingAction -> @getkist/action-sass
+ * - TypeScriptCompilerAction -> @getkist/action-typescript
+ * - JavaScriptMinifyAction -> @getkist/action-terser
+ * - SvgPackagerAction -> @getkist/action-svg
+ * - SvgSpriteAction -> @getkist/action-svg
+ * - SvgToPngAction -> @getkist/action-svg
+ * - SvgReaderAction -> @getkist/action-svg
+ * - LintAction -> @getkist/action-lint
+ * - DocumentationAction -> @getkist/action-docs
+ * - PackageManagerAction -> @getkist/action-package-manager
+ * - RunScriptAction -> @getkist/action-scripts
+ */
+
+export const CORE_ACTIONS = [
+    "DirectoryCleanAction",
+    "DirectoryCopyAction",
+    "DirectoryCreateAction",
+    "FileCopyAction",
+    "FileRenameAction",
+    "TemplateRenderAction",
+    "VersionWriteAction",
+] as const;
+
+export const PLUGIN_ACTIONS = [
+    // @getkist/action-sass
+    "StyleProcessingAction",
+
+    // @getkist/action-typescript
+    "TypeScriptCompilerAction",
+
+    // @getkist/action-terser
+    "JavaScriptMinifyAction",
+
+    // @getkist/action-svg
+    "SvgPackagerAction",
+    "SvgReaderAction",
+    "SvgSpriteAction",
+    "SvgToPngAction",
+
+    // @getkist/action-lint
+    "LintAction",
+
+    // @getkist/action-docs
+    "DocumentationAction",
+
+    // @getkist/action-package-manager
+    "PackageManagerAction",
+
+    // @getkist/action-scripts
+    "RunScriptAction",
+] as const;
+
+export type CoreActionName = (typeof CORE_ACTIONS)[number];
+export type PluginActionName = (typeof PLUGIN_ACTIONS)[number];
+
+/**
+ * Plugin package mappings for migration guide
+ */
+export const PLUGIN_PACKAGES: Record<
+    PluginActionName,
+    {
+        package: string;
+        npm: string;
+        github: string;
+    }
+> = {
+    StyleProcessingAction: {
+        package: "@getkist/action-sass",
+        npm: "npm install --save-dev @getkist/action-sass",
+        github: "https://github.com/getkist/kist-action-sass",
+    },
+    TypeScriptCompilerAction: {
+        package: "@getkist/action-typescript",
+        npm: "npm install --save-dev @getkist/action-typescript",
+        github: "https://github.com/getkist/kist-action-typescript",
+    },
+    JavaScriptMinifyAction: {
+        package: "@getkist/action-terser",
+        npm: "npm install --save-dev @getkist/action-terser",
+        github: "https://github.com/getkist/kist-action-terser",
+    },
+    SvgPackagerAction: {
+        package: "@getkist/action-svg",
+        npm: "npm install --save-dev @getkist/action-svg",
+        github: "https://github.com/getkist/kist-action-svg",
+    },
+    SvgReaderAction: {
+        package: "@getkist/action-svg",
+        npm: "npm install --save-dev @getkist/action-svg",
+        github: "https://github.com/getkist/kist-action-svg",
+    },
+    SvgSpriteAction: {
+        package: "@getkist/action-svg",
+        npm: "npm install --save-dev @getkist/action-svg",
+        github: "https://github.com/getkist/kist-action-svg",
+    },
+    SvgToPngAction: {
+        package: "@getkist/action-svg",
+        npm: "npm install --save-dev @getkist/action-svg",
+        github: "https://github.com/getkist/kist-action-svg",
+    },
+    LintAction: {
+        package: "@getkist/action-lint",
+        npm: "npm install --save-dev @getkist/action-lint",
+        github: "https://github.com/getkist/kist-action-lint",
+    },
+    DocumentationAction: {
+        package: "@getkist/action-docs",
+        npm: "npm install --save-dev @getkist/action-docs",
+        github: "https://github.com/getkist/kist-action-docs",
+    },
+    PackageManagerAction: {
+        package: "@getkist/action-package-manager",
+        npm: "npm install --save-dev @getkist/action-package-manager",
+        github: "https://github.com/getkist/kist-action-package-manager",
+    },
+    RunScriptAction: {
+        package: "@getkist/action-scripts",
+        npm: "npm install --save-dev @getkist/action-scripts",
+        github: "https://github.com/getkist/kist-action-scripts",
+    },
+};

package/ts/core/config/ConfigLoader.ts

@@ -71,7 +71,7 @@ export class ConfigLoader extends AbstractProcess {
                 this.configPath = resolvedPath;
                 this.logDebug(`Configuration file found: ${resolvedPath}`);
                 return;
-            } catch (error) {
+            } catch (_error) {
                 this.logDebug(`File not accessible: ${resolvedPath}`);
 
                 // ❗ If user explicitly provided --config and it fails, stop immediately
@@ -87,40 +87,6 @@ export class ConfigLoader extends AbstractProcess {
             "No configuration file found. Proceeding with default settings.",
         );
     }
-    // public async initialize(): Promise<void> {
-    //     const parser = new ArgumentParser();
-    //     const cliFlags = parser.getAllFlags();
-    //     const cliPath =
-    //         typeof cliFlags.config === "string" ? cliFlags.config : undefined;
-
-    //     const searchPaths = cliPath ? [cliPath] : this.defaultFilenames;
-
-    //     this.logDebug(`Current working directory: ${process.cwd()}`);
-    //     this.logDebug(
-    //         `Searching for config file${cliPath ? ` from --config=${cliPath}` : ""}...`,
-    //     );
-
-    //     for (const fileName of searchPaths) {
-    //         const resolvedPath = path.resolve(process.cwd(), fileName);
-    //         this.logDebug(`Checking: ${resolvedPath}`);
-
-    //         try {
-    //             await fs.promises.access(
-    //                 resolvedPath,
-    //                 fs.constants.F_OK | fs.constants.R_OK,
-    //             );
-    //             this.configPath = resolvedPath;
-    //             this.logDebug(`Configuration file found: ${resolvedPath}`);
-    //             return;
-    //         } catch (error) {
-    //             this.logDebug(`File not accessible: ${resolvedPath}`);
-    //         }
-    //     }
-
-    //     this.logWarn(
-    //         "No configuration file found. Proceeding with default settings.",
-    //     );
-    // }
 
     /**
      * Loads and validates the configuration file.

package/ts/core/config/ConfigStore copy.ts

@@ -97,13 +97,39 @@ export class ConfigStore extends AbstractProcess {
 
         for (let i = 0; i < keys.length - 1; i++) {
             const k = keys[i];
+
+            // Guard against prototype pollution
+            if (
+                k === "__proto__" ||
+                k === "constructor" ||
+                k === "prototype"
+            ) {
+                this.logWarn(
+                    `Attempted to set protected key "${k}". This operation is blocked for security reasons.`,
+                );
+                return;
+            }
+
             if (!current[k] || typeof current[k] !== "object") {
                 current[k] = {};
             }
             current = current[k];
         }
 
-        current[keys[keys.length - 1]] = value;
+        // Guard against prototype pollution for the final key
+        const finalKey = keys[keys.length - 1];
+        if (
+            finalKey === "__proto__" ||
+            finalKey === "constructor" ||
+            finalKey === "prototype"
+        ) {
+            this.logWarn(
+                `Attempted to set protected key "${finalKey}". This operation is blocked for security reasons.`,
+            );
+            return;
+        }
+
+        current[finalKey] = value;
         this.logDebug(
             `Set configuration key "${key}" to: ${JSON.stringify(value)}`,
         );

package/ts/core/pipeline/Action.ts

@@ -55,7 +55,7 @@ export abstract class Action
      * @returns A boolean indicating whether the options are valid. Default
      * implementation always returns true.
      */
-    validateOptions(options: ActionOptionsType): boolean {
+    validateOptions(_options: ActionOptionsType): boolean {
         // Default validation: always returns true, can be overridden in
         // derived classes
         return true;

package/ts/core/pipeline/ActionRegistry.ts

@@ -2,12 +2,10 @@
 // Import
 // ============================================================================
 
-import { readdirSync } from "fs";
-import { join } from "path";
 import { coreActions } from "../../actions/CoreActions";
 import { ActionInterface } from "../../interface/ActionInterface";
-import { ActionPlugin } from "../../interface/ActionPlugin";
 import { AbstractProcess } from "../abstract/AbstractProcess";
+import { PluginManager } from "../plugin/PluginManager";
 
 // ============================================================================
 // Class
@@ -46,7 +44,8 @@ export class ActionRegistry extends AbstractProcess {
         this.registry = new Map();
         // Automatically register core actions
         this.registerCoreActions();
-        this.discoverPlugins();
+        // Register plugin actions via PluginManager
+        this.registerPluginActions();
         this.logInfo("ActionRegistry initialized.");
     }
 
@@ -169,40 +168,27 @@ export class ActionRegistry extends AbstractProcess {
         this.logInfo("Core actions registered successfully.");
     }
 
-    private discoverPlugins(): void {
-        this.logInfo("Discovering external plugins...");
-
-        const nodeModulesPath = join(process.cwd(), "node_modules");
-        const pluginPrefix = "@kist/plugin-";
-
-        try {
-            const directories = readdirSync(nodeModulesPath, {
-                withFileTypes: true,
-            });
-
-            for (const dir of directories) {
-                if (dir.isDirectory() && dir.name.startsWith(pluginPrefix)) {
-                    const pluginPath = join(nodeModulesPath, dir.name);
-                    const plugin: ActionPlugin = require(pluginPath).default;
-
-                    if (
-                        plugin &&
-                        typeof plugin.registerActions === "function"
-                    ) {
-                        const actions = plugin.registerActions();
-                        for (const [name, actionClass] of Object.entries(
-                            actions,
-                        )) {
-                            this.registerAction(actionClass);
-                        }
-                    }
-                }
+    /**
+     * Registers actions from loaded plugins via PluginManager.
+     * This method integrates the plugin system with the action registry.
+     */
+    private registerPluginActions(): void {
+        const pluginManager = PluginManager.getInstance();
+        const pluginActions = pluginManager.getPluginActions();
+
+        for (const [actionName, actionClass] of pluginActions.entries()) {
+            try {
+                this.registerAction(actionClass);
+                this.logDebug(`Registered plugin action: ${actionName}`);
+            } catch (error) {
+                this.logError(
+                    `Failed to register plugin action ${actionName}:`,
+                    error,
+                );
             }
-
-            this.logInfo("Plugins loaded successfully.");
-        } catch (error) {
-            this.logError("Failed to discover plugins.", error);
         }
+
+        this.logInfo(`Registered ${pluginActions.size} actions from plugins.`);
     }
 
     /**

package/ts/core/pipeline/Step.ts

@@ -46,7 +46,7 @@ export class Step extends AbstractProcess {
         // const ActionClass = actionRegistry.getAction(step.action.name);
         const ActionClass = actionRegistry.getAction(String(step.action));
         if (!ActionClass) {
-            let msg = `
+            const msg = `
                 Unknown action "${step.action}" for step "${this.name}".
                 Ensure the action is registered in the registry.
                 `;

package/ts/core/plugin/PluginManager.ts

@@ -0,0 +1,310 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { readdirSync } from "fs";
+import { join } from "path";
+import { ActionInterface } from "../../interface/ActionInterface";
+import { ActionPlugin } from "../../interface/ActionPlugin";
+import { PluginMetadata } from "../../interface/PluginMetadata";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * PluginManager handles discovery, loading, and lifecycle of kist plugins.
+ * Supports both npm-installed plugins (@getkist/plugin-*) and local plugins.
+ */
+export class PluginManager extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    private static instance: PluginManager | null = null;
+    private loadedPlugins: Map<string, PluginMetadata> = new Map();
+    private pluginActions: Map<string, new () => ActionInterface> = new Map();
+
+    // Constructor
+    // ========================================================================
+
+    private constructor() {
+        super();
+        this.logInfo("PluginManager initialized.");
+    }
+
+    // Singleton Methods
+    // ========================================================================
+
+    public static getInstance(): PluginManager {
+        if (!PluginManager.instance) {
+            PluginManager.instance = new PluginManager();
+        }
+        return PluginManager.instance;
+    }
+
+    public static resetInstance(): void {
+        PluginManager.instance = null;
+    }
+
+    // Plugin Discovery
+    // ========================================================================
+
+    /**
+     * Discovers and loads all available plugins from:
+     * - node_modules/@getkist/plugin-*
+     * - node_modules/kist-plugin-*
+     * - Local plugins directory (if configured)
+     */
+    public async discoverPlugins(options?: {
+        localPluginsPath?: string;
+        pluginPrefixes?: string[];
+    }): Promise<void> {
+        this.logInfo("Starting plugin discovery...");
+
+        const prefixes = options?.pluginPrefixes || [
+            "@getkist/action-",
+            "kist-plugin-",
+        ];
+
+        // Discover npm plugins
+        await this.discoverNpmPlugins(prefixes);
+
+        // Discover local plugins if path provided
+        if (options?.localPluginsPath) {
+            await this.discoverLocalPlugins(options.localPluginsPath);
+        }
+
+        this.logInfo(
+            `Plugin discovery complete. Loaded ${this.loadedPlugins.size} plugins.`,
+        );
+    }
+
+    /**
+     * Discovers plugins installed via npm with specified prefixes
+     */
+    private async discoverNpmPlugins(prefixes: string[]): Promise<void> {
+        const nodeModulesPath = join(process.cwd(), "node_modules");
+
+        try {
+            const directories = readdirSync(nodeModulesPath, {
+                withFileTypes: true,
+            });
+
+            for (const dir of directories) {
+                // Check for scoped packages (@getkist/plugin-*)
+                if (dir.isDirectory() && dir.name.startsWith("@")) {
+                    await this.discoverScopedPlugins(
+                        join(nodeModulesPath, dir.name),
+                        prefixes,
+                    );
+                }
+
+                // Check for non-scoped packages (kist-plugin-*)
+                for (const prefix of prefixes) {
+                    if (
+                        dir.isDirectory() &&
+                        !prefix.startsWith("@") &&
+                        dir.name.startsWith(prefix)
+                    ) {
+                        await this.loadPlugin(
+                            join(nodeModulesPath, dir.name),
+                            dir.name,
+                        );
+                    }
+                }
+            }
+        } catch (error) {
+            this.logError("Failed to discover npm plugins.", error);
+        }
+    }
+
+    /**
+     * Discovers plugins in scoped packages (@getkist/*)
+     */
+    private async discoverScopedPlugins(
+        scopePath: string,
+        prefixes: string[],
+    ): Promise<void> {
+        try {
+            const packages = readdirSync(scopePath, { withFileTypes: true });
+
+            for (const pkg of packages) {
+                for (const prefix of prefixes) {
+                    const scopePrefix = prefix.split("/")[1]; // Extract "plugin-" from "@getkist/plugin-"
+                    if (
+                        pkg.isDirectory() &&
+                        scopePrefix &&
+                        pkg.name.startsWith(scopePrefix)
+                    ) {
+                        const fullName = `${scopePath.split("/").pop()}/${pkg.name}`;
+                        await this.loadPlugin(
+                            join(scopePath, pkg.name),
+                            fullName,
+                        );
+                    }
+                }
+            }
+        } catch (_error) {
+            this.logDebug(`No scoped plugins found in ${scopePath}`);
+        }
+    }
+
+    /**
+     * Discovers plugins from a local directory
+     */
+    private async discoverLocalPlugins(localPath: string): Promise<void> {
+        try {
+            const pluginPath = join(process.cwd(), localPath);
+            const directories = readdirSync(pluginPath, {
+                withFileTypes: true,
+            });
+
+            for (const dir of directories) {
+                if (dir.isDirectory()) {
+                    await this.loadPlugin(
+                        join(pluginPath, dir.name),
+                        `local:${dir.name}`,
+                    );
+                }
+            }
+        } catch (_error) {
+            this.logDebug(`No local plugins found at ${localPath}`);
+        }
+    }
+
+    // Plugin Loading
+    // ========================================================================
+
+    /**
+     * Loads a single plugin from the specified path
+     */
+    private async loadPlugin(
+        pluginPath: string,
+        pluginName: string,
+    ): Promise<void> {
+        try {
+            this.logDebug(`Loading plugin: ${pluginName}`);
+
+            const pluginModule = await import(pluginPath);
+            const plugin: ActionPlugin = pluginModule.default || pluginModule;
+
+            if (!plugin || typeof plugin.registerActions !== "function") {
+                this.logWarn(
+                    `Plugin ${pluginName} does not implement ActionPlugin interface.`,
+                );
+                return;
+            }
+
+            // Get plugin metadata if available
+            const metadata: PluginMetadata = {
+                name: pluginName,
+                version:
+                    typeof plugin.version === "string"
+                        ? plugin.version
+                        : "unknown",
+                description:
+                    typeof plugin.description === "string"
+                        ? plugin.description
+                        : undefined,
+                actions: [],
+            };
+
+            // Register actions from the plugin
+            const actions = plugin.registerActions();
+            for (const [actionName, actionClass] of Object.entries(actions)) {
+                this.pluginActions.set(actionName, actionClass);
+                metadata.actions.push(actionName);
+                this.logDebug(`  - Registered action: ${actionName}`);
+            }
+
+            this.loadedPlugins.set(pluginName, metadata);
+            this.logInfo(
+                `Plugin "${pluginName}" loaded successfully with ${metadata.actions.length} actions.`,
+            );
+        } catch (error) {
+            this.logError(`Failed to load plugin ${pluginName}:`, error);
+        }
+    }
+
+    /**
+     * Manually register a plugin programmatically
+     */
+    public registerPlugin(plugin: ActionPlugin, name: string): void {
+        this.logInfo(`Manually registering plugin: ${name}`);
+
+        const metadata: PluginMetadata = {
+            name,
+            version:
+                typeof plugin.version === "string"
+                    ? plugin.version
+                    : "unknown",
+            description:
+                typeof plugin.description === "string"
+                    ? plugin.description
+                    : undefined,
+            actions: [],
+        };
+
+        const actions = plugin.registerActions();
+        for (const [actionName, actionClass] of Object.entries(actions)) {
+            this.pluginActions.set(actionName, actionClass);
+            metadata.actions.push(actionName);
+        }
+
+        this.loadedPlugins.set(name, metadata);
+        this.logInfo(
+            `Plugin "${name}" registered with ${metadata.actions.length} actions.`,
+        );
+    }
+
+    // Plugin Queries
+    // ========================================================================
+
+    /**
+     * Gets all actions from loaded plugins
+     */
+    public getPluginActions(): Map<string, new () => ActionInterface> {
+        return new Map(this.pluginActions);
+    }
+
+    /**
+     * Gets metadata for all loaded plugins
+     */
+    public getLoadedPlugins(): PluginMetadata[] {
+        return Array.from(this.loadedPlugins.values());
+    }
+
+    /**
+     * Gets metadata for a specific plugin
+     */
+    public getPluginMetadata(name: string): PluginMetadata | undefined {
+        return this.loadedPlugins.get(name);
+    }
+
+    /**
+     * Checks if a specific plugin is loaded
+     */
+    public isPluginLoaded(name: string): boolean {
+        return this.loadedPlugins.has(name);
+    }
+
+    /**
+     * Lists all action names from plugins
+     */
+    public listPluginActions(): string[] {
+        return Array.from(this.pluginActions.keys());
+    }
+
+    // Cleanup
+    // ========================================================================
+
+    /**
+     * Clears all loaded plugins and their actions
+     */
+    public clearPlugins(): void {
+        this.loadedPlugins.clear();
+        this.pluginActions.clear();
+        this.logInfo("All plugins cleared.");
+    }
+}

package/ts/index.ts

@@ -22,3 +22,28 @@ export * from "./types";
 
 // CLI Functions (if required programmatically)
 export * from "./cli.js";
+
+// ============================================================================
+// Plugin System Exports
+// ============================================================================
+
+// Core plugin interfaces and types
+export { ActionInterface } from "./interface/ActionInterface";
+export { ActionPlugin } from "./interface/ActionPlugin";
+export { PluginMetadata } from "./interface/PluginMetadata";
+
+// Plugin management
+export { PluginManager } from "./core/plugin/PluginManager";
+
+// Action system
+export { Action } from "./core/pipeline/Action";
+export { ActionRegistry } from "./core/pipeline/ActionRegistry";
+
+// Configuration for plugin developers
+export {
+    CORE_ACTIONS,
+    PLUGIN_ACTIONS,
+    PLUGIN_PACKAGES,
+    type CoreActionName,
+    type PluginActionName,
+} from "./config/actions.config";