@cldmv/slothlet 2.9.0 → 2.10.0

package/README.md

@@ -253,6 +253,73 @@ api.hooks.on(
 const result = await api.math.add(2, 3);
 ```
 
+### Dynamic API Extension with addApi()
+
+Load additional modules at runtime and extend your API dynamically:
+
+```javascript
+import slothlet from "@cldmv/slothlet";
+
+const api = await slothlet({ dir: "./api" });
+
+// Add plugins at runtime
+await api.addApi("plugins", "./plugins-folder");
+api.plugins.myPlugin();
+
+// Create nested API structures
+await api.addApi("runtime.plugins", "./more-plugins");
+api.runtime.plugins.loader();
+
+// Add with metadata for security/authorization
+await api.addApi("plugins.trusted", "./trusted-plugins", {
+	trusted: true,
+	permissions: ["read", "write", "admin"],
+	version: "1.0.0"
+});
+
+await api.addApi("plugins.external", "./third-party", {
+	trusted: false,
+	permissions: ["read"]
+});
+
+// Access metadata on functions
+const meta = api.plugins.trusted.someFunc.__metadata;
+console.log(meta.trusted); // true
+console.log(meta.permissions); // ["read", "write", "admin"]
+```
+
+**Security & Authorization with metadataAPI:**
+
+```javascript
+// Inside your modules, use metadataAPI for runtime introspection
+import { metadataAPI } from "@cldmv/slothlet/runtime";
+
+export async function sensitiveOperation() {
+	// Check caller's metadata
+	const caller = await metadataAPI.caller();
+
+	if (!caller?.trusted) {
+		throw new Error("Unauthorized: Caller is not trusted");
+	}
+
+	if (!caller.permissions.includes("admin")) {
+		throw new Error("Unauthorized: Admin permission required");
+	}
+
+	// Proceed with secure operation
+	return "Success";
+}
+
+// Get metadata by path
+const meta = await metadataAPI.get("plugins.trusted.someFunc");
+
+// Get current function's metadata
+const self = await metadataAPI.self();
+console.log("My version:", self.version);
+```
+
+🔒 **For complete metadata system documentation, see [docs/METADATA.md](https://github.com/CLDMV/slothlet/blob/master/docs/METADATA.md)**
+
 ---
 
 ## 📚 Configuration Options
@@ -481,6 +548,7 @@ Key highlights:
 
 - **[Hook System](https://github.com/CLDMV/slothlet/blob/master/docs/HOOKS.md)** - Complete hook system documentation with 4 hook types, pattern matching, and examples
 - **[Context Propagation](https://github.com/CLDMV/slothlet/blob/master/docs/CONTEXT-PROPAGATION.md)** - EventEmitter and class instance context preservation
+- **[Metadata System](https://github.com/CLDMV/slothlet/blob/master/docs/METADATA.md)** - Function metadata tagging and runtime introspection for security, authorization, and auditing
 - **[Module Structure](https://github.com/CLDMV/slothlet/blob/master/docs/MODULE-STRUCTURE.md)** - Comprehensive module organization patterns and examples
 - **[API Flattening](https://github.com/CLDMV/slothlet/blob/master/docs/API-FLATTENING.md)** - The 5 flattening rules with decision tree and benefits
 

package/dist/lib/engine/slothlet_child.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/engine/slothlet_engine.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/engine/slothlet_esm.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/engine/slothlet_helpers.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/engine/slothlet_worker.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/als-eventemitter.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/api_builder/add_api.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.
@@ -21,9 +21,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolvePathFromCaller } from "@cldmv/slothlet/helpers/resolve-from-caller";
+import { cleanMetadata, tagLoadedFunctions } from "./metadata.mjs";
 
 
-export async function addApiFromFolder({ apiPath, folderPath, instance }) {
+export async function addApiFromFolder({ apiPath, folderPath, instance, metadata = {} }) {
 	if (!instance.loaded) {
 		throw new Error("[slothlet] Cannot add API: API not loaded. Call create() or load() first.");
 	}
@@ -47,9 +48,21 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 	}
 
 	
+	
+	
 	let resolvedFolderPath = folderPath;
-	if (!path.isAbsolute(folderPath)) {
+	const isAbsolute = path.isAbsolute(folderPath);
+
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: folderPath="${folderPath}"`);
+		console.log(`[DEBUG] addApi: isAbsolute=${isAbsolute}`);
+	}
+
+	if (!isAbsolute) {
 		resolvedFolderPath = resolvePathFromCaller(folderPath);
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Resolved relative path to: ${resolvedFolderPath}`);
+		}
 	}
 
 	
@@ -77,6 +90,29 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 		newModules = await instance.modes.eager.create.call(instance, resolvedFolderPath, instance.config.apiDepth || Infinity, 0);
 	}
 
+	
+	
+	
+	if (newModules && metadata && typeof metadata === "object" && Object.keys(metadata).length > 0) {
+		
+		const fullMetadata = {
+			...metadata,
+			sourceFolder: resolvedFolderPath
+		};
+
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Tagging functions with metadata:`, Object.keys(fullMetadata));
+		}
+
+		tagLoadedFunctions(newModules, fullMetadata, resolvedFolderPath);
+	} else if (newModules) {
+		
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Cleaning metadata from functions (no metadata provided)`);
+		}
+		cleanMetadata(newModules);
+	}
+
 	if (instance.config.debug) {
 		if (newModules && typeof newModules === "object") {
 			console.log(`[DEBUG] addApi: Loaded modules:`, Object.keys(newModules));
@@ -200,6 +236,25 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 		}
 
 		
+		
+		
+		const targetValue = currentTarget[finalKey];
+		if (typeof targetValue === "function" && targetValue.__slothletPath) {
+			
+			
+			const _ = targetValue.__trigger; 
+			await targetValue(); 
+			
+		}
+
+		const boundTargetValue = currentBoundTarget[finalKey];
+		if (typeof boundTargetValue === "function" && boundTargetValue.__slothletPath) {
+			
+			const _ = boundTargetValue.__trigger;
+			await boundTargetValue();
+		}
+
+		
 		if (!currentTarget[finalKey]) {
 			currentTarget[finalKey] = {};
 		}

package/dist/lib/helpers/api_builder/analysis.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.
@@ -55,14 +55,19 @@ export async function analyzeModule(modulePath, options = {}) {
 	const moduleUrl = pathToFileURL(modulePath).href;
 
 	
+	
 	let importUrl = moduleUrl;
+	const separator = moduleUrl.includes("?") ? "&" : "?";
+
+	
+	importUrl = `${moduleUrl}${separator}_t=${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
 	if (instance && instance.instanceId) {
 		const runtimeType = instance.config?.runtime || "async";
 
 		
 		if (runtimeType === "live") {
-			const separator = moduleUrl.includes("?") ? "&" : "?";
-			importUrl = `${moduleUrl}${separator}slothlet_instance=${instance.instanceId}`;
+			importUrl = `${importUrl}&slothlet_instance=${instance.instanceId}`;
 			importUrl = `${importUrl}&slothlet_runtime=${runtimeType}`;
 
 			
@@ -72,6 +77,11 @@ export async function analyzeModule(modulePath, options = {}) {
 		
 	}
 
+	if (debug) {
+		console.log(`[DEBUG] analyzeModule: Importing ${path.basename(modulePath)}`);
+		console.log(`[DEBUG]   URL: ${importUrl}`);
+	}
+
 	const rawModule = await import(importUrl);
 
 	

package/dist/lib/helpers/api_builder/construction.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/api_builder/decisions.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/api_builder/metadata.mjs

@@ -0,0 +1,248 @@
+/*
+	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.
+*/
+
+
+
+
+
+
+export function createImmutableMetadata(initial = {}) {
+	
+	
+	
+	function makeImmutable(obj, visited = new WeakSet()) {
+		if (obj === null || typeof obj !== "object") return obj;
+		if (visited.has(obj)) return obj;
+		visited.add(obj);
+
+		
+		if (Array.isArray(obj)) {
+			
+			for (let i = 0; i < obj.length; i++) {
+				obj[i] = makeImmutable(obj[i], visited);
+			}
+
+			
+			
+			return new Proxy(obj, {
+				set() {
+					
+					
+					return false;
+				},
+				deleteProperty() {
+					
+					return false;
+				}
+			});
+		}
+
+		
+		for (const [key, value] of Object.entries(obj)) {
+			const immutableValue = makeImmutable(value, visited);
+			Object.defineProperty(obj, key, {
+				value: immutableValue,
+				writable: false, 
+				enumerable: true,
+				configurable: true
+			});
+		}
+
+		
+		return new Proxy(obj, {
+			set(target, prop, value) {
+				const descriptor = Object.getOwnPropertyDescriptor(target, prop);
+
+				
+				if (descriptor && !descriptor.writable) {
+					return false;
+				}
+
+				
+				if (!descriptor) {
+					const immutableValue = makeImmutable(value);
+					Object.defineProperty(target, prop, {
+						value: immutableValue,
+						writable: false,
+						enumerable: true,
+						configurable: true
+					});
+					return true;
+				}
+
+				return Reflect.set(target, prop, value);
+			},
+			deleteProperty() {
+				
+				return false;
+			}
+		});
+	}
+
+	
+	const base = {};
+
+	
+	
+	for (const [key, value] of Object.entries(initial)) {
+		const immutableValue = makeImmutable(value);
+		Object.defineProperty(base, key, {
+			value: immutableValue,
+			writable: false,
+			enumerable: true,
+			configurable: true 
+		});
+	}
+
+	
+	return new Proxy(base, {
+		set(target, prop, value) {
+			
+			const descriptor = Object.getOwnPropertyDescriptor(target, prop);
+
+			
+			if (descriptor && !descriptor.writable) {
+				if (process.env.SLOTHLET_DEBUG) {
+					console.warn(`[slothlet] Cannot modify existing metadata property: "${String(prop)}"`);
+				}
+				
+				
+				return false;
+			}
+
+			
+			if (!descriptor) {
+				Object.defineProperty(target, prop, {
+					value,
+					writable: false,
+					enumerable: true,
+					configurable: true 
+				});
+				return true;
+			}
+
+			
+			
+			return Reflect.set(target, prop, value);
+		},
+
+		deleteProperty(target, prop) {
+			
+			if (process.env.SLOTHLET_DEBUG) {
+				console.warn(`[slothlet] Cannot delete metadata property: "${String(prop)}"`);
+			}
+			return true; 
+		}
+	});
+}
+
+
+export function cleanMetadata(obj, visited = new WeakSet()) {
+	
+	if (!obj || (typeof obj !== "object" && typeof obj !== "function")) return;
+	if (visited.has(obj)) return;
+	visited.add(obj);
+
+	
+	if (typeof obj === "function") {
+		try {
+			if (obj.__metadata) {
+				delete obj.__metadata;
+			}
+			if (obj.__sourceFolder) {
+				delete obj.__sourceFolder;
+			}
+		} catch (_) {
+			
+		}
+	}
+
+	
+	try {
+		const keys = Object.keys(obj);
+		for (const key of keys) {
+			if (
+				key.startsWith("_") ||
+				["hooks", "shutdown", "addApi", "describe", "run", "__proto__", "constructor", "prototype"].includes(key)
+			) {
+				continue;
+			}
+			cleanMetadata(obj[key], visited);
+		}
+	} catch {
+		
+	}
+}
+
+
+export function tagLoadedFunctions(obj, metadata, baseDir, visited = new WeakSet()) {
+	
+	if (!obj || (typeof obj !== "object" && typeof obj !== "function")) return;
+	if (visited.has(obj)) return;
+	visited.add(obj);
+
+	
+	if (typeof obj === "function") {
+		try {
+			
+			const immutableMeta = createImmutableMetadata(metadata);
+
+			Object.defineProperty(obj, "__metadata", {
+				value: immutableMeta,
+				writable: false,
+				enumerable: false,
+				configurable: true 
+			});
+
+			
+			if (metadata.sourceFolder) {
+				Object.defineProperty(obj, "__sourceFolder", {
+					value: metadata.sourceFolder,
+					writable: false,
+					enumerable: false,
+					configurable: true 
+				});
+			}
+
+			
+			
+			
+		} catch (error) {
+			
+			if (metadata.debug) {
+				console.warn(`[slothlet] Could not tag function with metadata:`, error.message);
+			}
+		}
+	}
+
+	
+	try {
+		const keys = Object.keys(obj);
+		for (const key of keys) {
+			
+			if (
+				key.startsWith("_") ||
+				["hooks", "shutdown", "addApi", "describe", "run", "__proto__", "constructor", "prototype"].includes(key)
+			) {
+				continue;
+			}
+
+			tagLoadedFunctions(obj[key], metadata, baseDir, visited);
+		}
+	} catch {
+		
+	}
+}

package/dist/lib/helpers/api_builder.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/auto-wrap.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/hooks.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/instance-manager.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.