@cldmv/slothlet 2.9.0 → 2.11.0

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.
@@ -66,7 +66,8 @@ export async function buildCategoryStructure(categoryPath, options = {}) {
 		maxDepth,
 		mode,
 		subdirHandler,
-		instance
+		instance,
+		existingApi: options.existingApi
 	});
 
 	
@@ -320,6 +321,34 @@ export async function buildCategoryStructure(categoryPath, options = {}) {
 	}
 
 	
+	
+	let defaultFunctions = [];
+	for (const moduleDecision of processedModules) {
+		const { mod, type } = moduleDecision;
+		if (type === "function" && typeof mod === "function") {
+			defaultFunctions.push({ mod, moduleDecision });
+		}
+	}
+
+	
+	
+	
+	if (defaultFunctions.length === 1 && Object.keys(categoryModules).length === 1) {
+		const categoryDefaultFunction = defaultFunctions[0].mod;
+
+		
+		if (categoryDefaultFunction.name !== categoryName) {
+			try {
+				Object.defineProperty(categoryDefaultFunction, "name", { value: categoryName, configurable: true });
+			} catch {
+				
+			}
+		}
+
+		return categoryDefaultFunction;
+	}
+
+	
 	const keys = Object.keys(categoryModules);
 	if (keys.length === 1) {
 		const singleKey = keys[0];
@@ -416,7 +445,16 @@ export async function buildRootAPI(dir, options = {}) {
 
 			if (lazy) {
 				
-				api[instance._toapiPathKey(entry.name)] = await instance._loadCategory(categoryPath, 0, maxDepth);
+				api[instance._toapiPathKey(entry.name)] = await buildCategoryStructure(categoryPath, {
+					currentDepth: 1,
+					maxDepth,
+					mode: "lazy",
+					subdirHandler: (ctx) => {
+						
+						return instance._loadCategory(ctx.subDirPath, ctx.currentDepth, ctx.maxDepth);
+					},
+					instance
+				});
 			} else {
 				
 				api[instance._toapiPathKey(entry.name)] = await buildCategoryStructure(categoryPath, {

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.
@@ -321,10 +321,21 @@ export function processModuleForAPI(options) {
 
 	
 	for (const [key, value] of Object.entries(apiAssignments)) {
-		if (debug && key && typeof value === "function" && value.name) {
-			console.log(`[DEBUG] ${mode}: Assigning key '${key}' to function '${value.name}'`);
+		if (debug) {
+			console.log(`[DEBUG] ${mode}: About to assign key '${key}' - current api[${key}]:`, api[key] ? Object.keys(api[key]) : "undefined");
+			console.log(`[DEBUG] ${mode}: New value for key '${key}':`, typeof value === "object" && value ? Object.keys(value) : typeof value);
+		}
+
+		
+		if (api[key] && typeof api[key] === "object" && typeof value === "object" && !Array.isArray(api[key]) && !Array.isArray(value)) {
+			if (debug) {
+				console.log(`[DEBUG] ${mode}: Merging objects for key '${key}' - existing:`, Object.keys(api[key]), "new:", Object.keys(value));
+			}
+			
+			Object.assign(api[key], value);
+		} else {
+			api[key] = value;
 		}
-		api[key] = value;
 	}
 
 	return {
@@ -342,7 +353,7 @@ export function processModuleForAPI(options) {
 
 
 export async function buildCategoryDecisions(categoryPath, options = {}) {
-	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
+	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler, existingApi: _ } = options;
 	const { instance } = options;
 
 	if (!instance || typeof instance._toapiPathKey !== "function") {

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.

package/dist/lib/helpers/metadata-api.mjs

@@ -0,0 +1,201 @@
+/*
+	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 { getStack, toFsPath } from "@cldmv/slothlet/helpers/resolve-from-caller";
+
+
+let runtimeModule = null;
+let runtimeImportPromise = null;
+
+
+async function ensureRuntime() {
+	if (runtimeModule) {
+		return runtimeModule;
+	}
+
+	if (!runtimeImportPromise) {
+		runtimeImportPromise = import("@cldmv/slothlet/runtime")
+			.then((module) => {
+				runtimeModule = module;
+				return module;
+			})
+			.catch((err) => {
+				console.error("[slothlet] Failed to import runtime for metadata API:", err.message);
+				runtimeModule = {}; 
+				return {};
+			});
+	}
+
+	return runtimeImportPromise;
+}
+
+
+function getApiRoot() {
+	
+	return runtimeModule?.self || null;
+}
+
+
+function findFunctionByStack(apiRoot, targetFile, targetLine, visited = new WeakSet()) {
+	if (!apiRoot || visited.has(apiRoot)) return null;
+	visited.add(apiRoot);
+
+	
+	if (typeof apiRoot === "function" && apiRoot.__sourceFile && apiRoot.__sourceLine) {
+		if (apiRoot.__sourceFile === targetFile && apiRoot.__sourceLine === targetLine) {
+			return apiRoot;
+		}
+	}
+
+	
+	if (typeof apiRoot === "object" || typeof apiRoot === "function") {
+		const keys = Object.keys(apiRoot);
+		for (const key of keys) {
+			
+			if (key.startsWith("_") || ["hooks", "shutdown", "addApi", "describe", "run"].includes(key)) {
+				continue;
+			}
+
+			const result = findFunctionByStack(apiRoot[key], targetFile, targetLine, visited);
+			if (result) return result;
+		}
+	}
+
+	return null;
+}
+
+
+function findFunctionByPath(apiRoot, path) {
+	if (!path || typeof path !== "string") return null;
+
+	const parts = path.split(".");
+	let current = apiRoot;
+
+	for (const part of parts) {
+		if (!current || (typeof current !== "object" && typeof current !== "function")) {
+			if (process.env.SLOTHLET_DEBUG) {
+				console.log("[findFunctionByPath] Failed: current is", typeof current);
+			}
+			return null;
+		}
+		current = current[part];
+	}
+
+	const result = typeof current === "function" ? current : null;
+	if (process.env.SLOTHLET_DEBUG) {
+		console.log("[findFunctionByPath] Result:", result ? "function found" : "null");
+	}
+	return result;
+}
+
+
+function parseCallSite(cs) {
+	if (!cs) return null;
+
+	const fileName = cs.getFileName?.();
+	if (!fileName) return null;
+
+	
+	const filePath = toFsPath(fileName);
+	if (!filePath) return null;
+
+	
+	if (filePath.startsWith?.("node:internal")) return null;
+
+	const lineNum = cs.getLineNumber?.();
+	if (typeof lineNum !== "number") return null;
+
+	return { file: filePath, line: lineNum };
+}
+
+
+export const metadataAPI = {
+	
+	async caller() {
+		
+		await ensureRuntime();
+
+		
+		const apiRoot = getApiRoot();
+		if (!apiRoot || typeof apiRoot !== "object") return null;
+
+		
+		const stack = getStack(metadataAPI.caller);
+
+		
+		
+		
+		if (stack.length < 1) return null;
+
+		const parsed = parseCallSite(stack[0]);
+		if (!parsed) return null;
+
+		
+		const func = findFunctionByStack(apiRoot, parsed.file, parsed.line);
+		if (!func) return null;
+
+		
+		return func.__metadata || null;
+	},
+
+	
+	async self() {
+		
+		await ensureRuntime();
+
+		
+		const apiRoot = getApiRoot();
+		if (!apiRoot || typeof apiRoot !== "object") return null;
+
+		
+		const stack = getStack(metadataAPI.self);
+
+		
+		if (stack.length < 1) return null;
+
+		const parsed = parseCallSite(stack[0]);
+		if (!parsed) return null;
+
+		
+		const func = findFunctionByStack(apiRoot, parsed.file, parsed.line);
+		if (!func) return null;
+
+		
+		return func.__metadata || null;
+	},
+
+	
+	async get(path, apiRoot) {
+		
+		await ensureRuntime();
+
+		
+		const root = apiRoot || getApiRoot();
+		if (!root || (typeof root !== "object" && typeof root !== "function")) {
+			return null;
+		}
+
+		const func = findFunctionByPath(root, path);
+		if (!func) return null;
+
+		
+		return func.__metadata || null;
+	}
+};

package/dist/lib/helpers/multidefault.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.
@@ -39,10 +39,19 @@ async function multidefault_analyzeModules(moduleFiles, baseDir, options = {}) {
 		const moduleFilePath = path.resolve(baseDir, file.name);
 
 		
+		
 		let importUrl = `file://${moduleFilePath.replace(/\\/g, "/")}`;
+		const separator = importUrl.includes("?") ? "&" : "?";
+
+		
+		importUrl = `${importUrl}${separator}_t=${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
+		
 		if (instance && instance.instanceId) {
-			const separator = importUrl.includes("?") ? "&" : "?";
-			importUrl = `${importUrl}${separator}slothlet_instance=${instance.instanceId}`;
+			const runtimeType = instance.config?.runtime || "async";
+			if (runtimeType === "live") {
+				importUrl = `${importUrl}&slothlet_instance=${instance.instanceId}`;
+			}
 		}