@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/handlers/hook-manager.mjs

@@ -0,0 +1,789 @@
+/*
+	Copyright 2026 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+
+
+
+
+const ERROR_HOOK_PROCESSED = Symbol.for("@cldmv/slothlet/hook-error-processed");
+
+
+export class HookManager extends ComponentBase {
+	
+	static slothletProperty = "hookManager";
+
+	
+	#hooks = {
+		before: { before: {}, primary: {}, after: {} },
+		after: { before: {}, primary: {}, after: {} },
+		always: { before: {}, primary: {}, after: {} },
+		error: { before: {}, primary: {}, after: {} }
+	};
+
+	
+	#byId = new Map();
+
+	
+	#idCounter = 0;
+
+	
+	#validTypes = new Set(["before", "after", "always", "error"]);
+
+	
+	#validSubsets = new Set(["before", "primary", "after"]);
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+
+		
+		const hookConfig = slothlet.config?.hook || { enabled: false, pattern: "**", suppressErrors: false };
+
+		this.enabled = hookConfig.enabled;
+		this.defaultPattern = hookConfig.pattern || "**";
+		this.suppressErrors = hookConfig.suppressErrors || false;
+		this.enabledPatterns = new Set(); 
+		this.patternFilterActive = false; 
+
+		this.hooks = new Map(); 
+		this.registrationOrder = 0; 
+		this.reportedErrors = new WeakSet(); 
+	}
+
+	
+	on(typePattern, handler, options = {}) {
+		
+		let { type, pattern } = this.#parseTypePattern(typePattern);
+
+		
+		if (options.pattern !== undefined) {
+			pattern = options.pattern;
+		}
+
+		
+		if (!this.#validTypes.has(type)) {
+			throw new this.slothlet.SlothletError("INVALID_HOOK_TYPE", {
+				type,
+				validTypes: Array.from(this.#validTypes)
+			});
+		}
+
+		
+		if (typeof handler !== "function") {
+			throw new this.slothlet.SlothletError("INVALID_HOOK_HANDLER", {
+				receivedType: typeof handler,
+				validationError: true
+			});
+		}
+
+		
+		const id = options.id || this.#generateId();
+
+		
+		if (this.#byId.has(id)) {
+			throw new this.slothlet.SlothletError("DUPLICATE_HOOK_ID", { id, validationError: true });
+		}
+
+		
+		const subset = options.subset || "primary";
+		if (!this.#validSubsets.has(subset)) {
+			throw new this.slothlet.SlothletError("INVALID_HOOK_SUBSET", {
+				subset,
+				validSubsets: Array.from(this.#validSubsets)
+			});
+		}
+
+		
+		this.#compilePattern(pattern);
+
+		
+		const hook = {
+			id,
+			type,
+			pattern,
+			handler,
+			priority: options.priority || 0,
+			subset,
+			enabled: true,
+			_compiled: null 
+		};
+
+		
+		const typeIndex = this.#hooks[type];
+		const subsetIndex = typeIndex[subset];
+
+		if (!subsetIndex[pattern]) {
+			subsetIndex[pattern] = [];
+		}
+		subsetIndex[pattern].push(hook);
+
+		
+		this.#byId.set(id, hook);
+
+		return id;
+	}
+
+	
+	remove(filter = {}) {
+		let removed = 0;
+
+		
+		if (filter.id) {
+			const hook = this.#byId.get(filter.id);
+			if (hook) {
+				this.#removeHook(hook);
+				removed = 1;
+			}
+			return removed;
+		}
+
+		
+		const types = filter.type ? [filter.type] : Array.from(this.#validTypes);
+
+		for (const type of types) {
+			const typeIndex = this.#hooks[type];
+
+			for (const subset of ["before", "primary", "after"]) {
+				const subsetIndex = typeIndex[subset];
+
+				
+				if (filter.pattern) {
+					const patternHooks = subsetIndex[filter.pattern];
+					if (patternHooks) {
+						removed += patternHooks.length;
+						patternHooks.forEach((hook) => this.#byId.delete(hook.id));
+						delete subsetIndex[filter.pattern];
+					}
+				} else {
+					
+					for (const pattern in subsetIndex) {
+						const patternHooks = subsetIndex[pattern];
+						removed += patternHooks.length;
+						patternHooks.forEach((hook) => this.#byId.delete(hook.id));
+						delete subsetIndex[pattern];
+					}
+				}
+			}
+		}
+
+		return removed;
+	}
+
+	
+	enable(filter = {}) {
+		
+		if (typeof filter === "string") {
+			filter = { pattern: filter };
+		}
+
+		
+		this.enabled = true;
+
+		return this.#setEnabledState(filter, true);
+	}
+
+	
+	disable(filter = {}) {
+		
+		if (typeof filter === "string") {
+			filter = { pattern: filter };
+		}
+
+		
+		if (Object.keys(filter).length === 0) {
+			this.enabled = false;
+		}
+		return this.#setEnabledState(filter, false);
+	}
+
+	
+	list(filter = {}) {
+		
+		if (typeof filter === "string") {
+			
+			if (this.#validTypes.has(filter)) {
+				filter = { type: filter };
+			} else {
+				
+				filter = { pattern: filter };
+			}
+		}
+
+		const hooks = [];
+
+		
+		if (filter.id) {
+			const hook = this.#byId.get(filter.id);
+			if (hook && (filter.enabled === undefined || hook.enabled === filter.enabled)) {
+				hooks.push(this.#serializeHook(hook));
+			}
+			return { registeredHooks: hooks };
+		}
+
+		
+		const types = filter.type ? [filter.type] : Array.from(this.#validTypes);
+
+		
+		let patternMatcher = null;
+		if (filter.pattern) {
+			patternMatcher = this.#compilePattern(filter.pattern);
+		}
+
+		for (const type of types) {
+			const typeIndex = this.#hooks[type];
+
+			for (const subset of ["before", "primary", "after"]) {
+				const subsetIndex = typeIndex[subset];
+
+				
+				for (const pattern in subsetIndex) {
+					const patternHooks = subsetIndex[pattern];
+					for (const hook of patternHooks) {
+						
+						if (filter.enabled !== undefined && hook.enabled !== filter.enabled) {
+							continue;
+						}
+
+						
+						if (patternMatcher && !patternMatcher(hook.pattern)) {
+							continue;
+						}
+
+						hooks.push(this.#serializeHook(hook));
+					}
+				}
+			}
+		}
+
+		return { registeredHooks: hooks };
+	}
+
+	
+	getHooksForPath(type, apiPath) {
+		
+		if (this.enabled === false) {
+			return [];
+		}
+
+		const typeIndex = this.#hooks[type];
+		if (!typeIndex) {
+			return [];
+		}
+
+		const hooks = [];
+
+		
+		for (const subset of ["before", "primary", "after"]) {
+			const subsetIndex = typeIndex[subset];
+			const subsetHooks = [];
+
+			
+			for (const pattern in subsetIndex) {
+				const patternHooks = subsetIndex[pattern];
+
+				
+				if (pattern === apiPath) {
+					subsetHooks.push(...patternHooks.filter((h) => h.enabled));
+					continue;
+				}
+
+				
+				for (const hook of patternHooks) {
+					if (!hook.enabled) continue;
+
+					if (!hook._compiled) {
+						hook._compiled = this.#compilePattern(hook.pattern);
+					}
+
+					if (hook._compiled(apiPath)) {
+						subsetHooks.push(hook);
+					}
+				}
+			}
+
+			
+			subsetHooks.sort((a, b) => b.priority - a.priority);
+
+			
+			hooks.push(...subsetHooks);
+		}
+
+		return hooks;
+	}
+
+	
+	executeBeforeHooks(path, args, api, ctx) {
+		const hooks = this.getHooksForPath("before", path);
+
+		for (const hook of hooks) {
+			try {
+				const result = hook.handler({ path, args, api, ctx });
+
+				
+				if (result && typeof result === "object" && typeof result.then === "function") {
+					throw new this.SlothletError("HOOK_BEFORE_RETURNED_PROMISE", { id: hook.id, path }, null, { validationError: true });
+				}
+
+				
+				if (result !== undefined && !Array.isArray(result)) {
+					return { args, shortCircuit: true, value: result };
+				}
+
+				
+				if (Array.isArray(result)) {
+					args = result;
+				}
+			} catch (error) {
+				
+				const sourceInfo = {
+					type: "before",
+					subset: hook.subset,
+					hookTag: hook.id,
+					hookId: hook.id,
+					timestamp: Date.now(),
+					stack: error.stack
+				};
+				this.executeErrorHooks(path, error, sourceInfo, args, api, ctx);
+				
+				if (!this.suppressErrors) {
+					throw error;
+				}
+				
+				return { args, shortCircuit: true, value: undefined };
+			}
+		}
+
+		return { args, shortCircuit: false };
+	}
+
+	
+	executeAfterHooks(path, result, args, api, ctx) {
+		const hooks = this.getHooksForPath("after", path);
+		const originalResult = result;
+		let currentResult = result;
+
+		for (const hook of hooks) {
+			try {
+				const hookContext = {
+					path,
+					args,
+					result: currentResult,
+					api,
+					ctx
+				};
+				const transformed = hook.handler(hookContext);
+
+				
+				if (transformed !== undefined) {
+					currentResult = transformed;
+				}
+			} catch (error) {
+				
+				const sourceInfo = {
+					type: "after",
+					subset: hook.subset,
+					hookTag: hook.id,
+					hookId: hook.id,
+					timestamp: Date.now(),
+					stack: error.stack
+				};
+				this.executeErrorHooks(path, error, sourceInfo, args, api, ctx);
+				
+				if (!this.suppressErrors) {
+					throw error;
+				}
+			}
+		}
+
+		
+		if (currentResult === originalResult) {
+			return { modified: false };
+		} else {
+			return { modified: true, result: currentResult };
+		}
+	}
+
+	
+	executeAlwaysHooks(path, args, resultOrError, hasError = false, errors = [], api, ctx) {
+		const hooks = this.getHooksForPath("always", path);
+
+		for (const hook of hooks) {
+			try {
+				hook.handler({
+					path,
+					args,
+					result: hasError ? undefined : resultOrError,
+					hasError,
+					errors: errors,
+					api,
+					ctx
+				});
+			} catch (error) {
+				
+				const sourceInfo = {
+					type: "always",
+					subset: hook.subset,
+					hookTag: hook.id,
+					hookId: hook.id,
+					timestamp: Date.now(),
+					stack: error.stack
+				};
+				this.executeErrorHooks(path, error, sourceInfo, args, api, ctx);
+			}
+		}
+	}
+
+	
+	executeErrorHooks(path, error, source, args, api, ctx) {
+		
+		if (error && typeof error === "object") {
+			error[ERROR_HOOK_PROCESSED] = true;
+		}
+
+		const hooks = this.getHooksForPath("error", path);
+
+		for (const hook of hooks) {
+			try {
+				hook.handler({
+					path,
+					args,
+					error,
+					errorType: error?.constructor?.name || "Error",
+					source,
+					timestamp: new Date(),
+					api,
+					ctx
+				});
+			} catch (hookError) {
+				
+				this.slothlet.debug("hooks", `Error hook failed for ${path}:`, hookError);
+			}
+		}
+	}
+
+	
+	#parseTypePattern(typePattern) {
+		if (typeof typePattern !== "string") {
+			throw new this.slothlet.SlothletError("INVALID_TYPE_PATTERN", {
+				typePattern,
+				expected: "string in format 'type:pattern'"
+			});
+		}
+
+		const colonIndex = typePattern.indexOf(":");
+		if (colonIndex === -1) {
+			throw new this.slothlet.SlothletError("INVALID_TYPE_PATTERN", {
+				typePattern,
+				expected: "string in format 'type:pattern' with at least one colon"
+			});
+		}
+
+		const type = typePattern.substring(0, colonIndex);
+		const pattern = typePattern.substring(colonIndex + 1);
+
+		if (!type || !pattern) {
+			throw new this.slothlet.SlothletError("INVALID_TYPE_PATTERN", {
+				typePattern,
+				expected: "non-empty type and pattern"
+			});
+		}
+
+		return { type, pattern };
+	}
+
+	
+	#compilePattern(pattern) {
+		
+		const isNegation = pattern.startsWith("!");
+		if (isNegation) {
+			pattern = pattern.slice(1);
+			const matcher = this.#compilePattern(pattern);
+			return (path) => !matcher(path);
+		}
+
+		
+		const expanded = this.#expandBraces(pattern);
+		if (expanded.length > 1) {
+			
+			const matchers = expanded.map((p) => this.#compilePattern(p));
+			return (path) => matchers.some((m) => m(path));
+		}
+
+		
+		pattern = expanded[0];
+
+		
+		let regexPattern = pattern
+			.replace(/[+^$()|[\]\\]/g, "\\$&") 
+			.replace(/\*\*/g, "__DOUBLESTAR__") 
+			.replace(/\*/g, "[^.]*") 
+			.replace(/__DOUBLESTAR__/g, ".*") 
+			.replace(/\?/g, "."); 
+
+		regexPattern = `^${regexPattern}$`;
+		const regex = new RegExp(regexPattern);
+
+		return (path) => regex.test(path);
+	}
+
+	
+	#expandBraces(pattern, depth = 0, maxDepth = 10) {
+		
+		if (depth >= maxDepth) {
+			throw new this.SlothletError("HOOK_BRACE_EXPANSION_MAX_DEPTH", { maxDepth }, null, { validationError: true });
+		}
+
+		
+		const braceStart = pattern.indexOf("{");
+		if (braceStart === -1) {
+			return [pattern]; 
+		}
+
+		
+		let braceEnd = -1;
+		let depth_count = 1;
+		for (let i = braceStart + 1; i < pattern.length; i++) {
+			if (pattern[i] === "{") depth_count++;
+			if (pattern[i] === "}") {
+				depth_count--;
+				if (depth_count === 0) {
+					braceEnd = i;
+					break;
+				}
+			}
+		}
+
+		if (braceEnd === -1) {
+			return [pattern]; 
+		}
+
+		
+		const prefix = pattern.slice(0, braceStart);
+		const braceContent = pattern.slice(braceStart + 1, braceEnd);
+		const suffix = pattern.slice(braceEnd + 1);
+
+		
+		const alternatives = this.#splitBraceAlternatives(braceContent);
+
+		
+		const expanded = [];
+		for (const alt of alternatives) {
+			const combined = prefix + alt + suffix;
+			
+			const recursiveExpanded = this.#expandBraces(combined, depth + 1, maxDepth);
+			expanded.push(...recursiveExpanded);
+		}
+
+		return expanded;
+	}
+
+	
+	#splitBraceAlternatives(content) {
+		const alternatives = [];
+		let current = "";
+		let depth = 0;
+
+		for (let i = 0; i < content.length; i++) {
+			const char = content[i];
+
+			if (char === "{") {
+				depth++;
+				current += char;
+			} else if (char === "}") {
+				depth--;
+				current += char;
+			} else if (char === "," && depth === 0) {
+				alternatives.push(current);
+				current = "";
+			} else {
+				current += char;
+			}
+		}
+
+		if (current) {
+			alternatives.push(current);
+		}
+
+		return alternatives;
+	}
+
+	
+	getCompilePatternForDiagnostics() {
+		return this.#compilePattern.bind(this);
+	}
+
+	
+	#generateId() {
+		return `hook-${++this.#idCounter}`;
+	}
+
+	
+	#removeHook(hook) {
+		const typeIndex = this.#hooks[hook.type];
+		const subsetIndex = typeIndex[hook.subset];
+		const patternHooks = subsetIndex[hook.pattern];
+
+		
+		
+		
+		
+		
+		
+		
+		if (!patternHooks) {
+			throw new this.slothlet.SlothletError("INTERNAL_HOOK_STATE_CORRUPT", {
+				hookId: hook.id,
+				type: hook.type,
+				subset: hook.subset,
+				pattern: hook.pattern,
+				detail: "patternHooks array missing from subsetIndex — #byId and #hooks are desynced"
+			});
+		}
+
+		const index = patternHooks.indexOf(hook);
+
+		
+		
+		
+		
+		
+		
+		if (index === -1) {
+			throw new this.slothlet.SlothletError("INTERNAL_HOOK_STATE_CORRUPT", {
+				hookId: hook.id,
+				type: hook.type,
+				subset: hook.subset,
+				pattern: hook.pattern,
+				detail: "hook object not found in patternHooks array — #byId and #hooks are desynced"
+			});
+		}
+
+		patternHooks.splice(index, 1);
+
+		
+		if (patternHooks.length === 0) {
+			delete subsetIndex[hook.pattern];
+		}
+
+		this.#byId.delete(hook.id);
+	}
+
+	
+	#setEnabledState(filter, enabled) {
+		let affected = 0;
+
+		
+		if (filter.id) {
+			const hook = this.#byId.get(filter.id);
+			if (hook) {
+				hook.enabled = enabled;
+				affected = 1;
+			}
+			return affected;
+		}
+
+		
+		const types = filter.type ? [filter.type] : Array.from(this.#validTypes);
+
+		for (const type of types) {
+			const typeIndex = this.#hooks[type];
+
+			for (const subset of ["before", "primary", "after"]) {
+				const subsetIndex = typeIndex[subset];
+
+				
+				if (filter.pattern) {
+					const patternHooks = subsetIndex[filter.pattern] || [];
+					for (const hook of patternHooks) {
+						hook.enabled = enabled;
+						affected++;
+					}
+				} else {
+					
+					for (const pattern in subsetIndex) {
+						const patternHooks = subsetIndex[pattern];
+						for (const hook of patternHooks) {
+							hook.enabled = enabled;
+							affected++;
+						}
+					}
+				}
+			}
+		}
+
+		return affected;
+	}
+
+	
+	#serializeHook(hook) {
+		return {
+			id: hook.id,
+			type: hook.type,
+			pattern: hook.pattern,
+			priority: hook.priority,
+			subset: hook.subset,
+			enabled: hook.enabled
+			
+		};
+	}
+
+	
+	exportHooks() {
+		const registrations = [];
+		for (const hook of this.#byId.values()) {
+			registrations.push({
+				typePattern: `${hook.type}:${hook.pattern}`,
+				handler: hook.handler,
+				options: {
+					id: hook.id,
+					priority: hook.priority,
+					subset: hook.subset
+				},
+				enabled: hook.enabled
+			});
+		}
+		return registrations;
+	}
+
+	
+	importHooks(registrations) {
+		if (!Array.isArray(registrations)) return;
+		for (const reg of registrations) {
+			this.on(reg.typePattern, reg.handler, reg.options);
+			if (!reg.enabled) {
+				this.disable({ id: reg.options.id });
+			}
+		}
+	}
+
+	
+	async shutdown() {
+		
+		this.#hooks = {
+			before: { before: {}, primary: {}, after: {} },
+			after: { before: {}, primary: {}, after: {} },
+			always: { before: {}, primary: {}, after: {} },
+			error: { before: {}, primary: {}, after: {} }
+		};
+		this.#byId.clear();
+		this.#idCounter = 0;
+	}
+}