@cldmv/slothlet 2.9.0 → 2.11.0

package/dist/lib/helpers/resolve-from-caller.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,37 +55,74 @@ function pickPrimaryBaseFile() {
 	for (const cs of getStack(pickPrimaryBaseFile)) {
 		const f = toFsPath(cs?.getFileName?.());
 		if (!f) continue;
-		if (f.startsWith?.("node:internal")) continue;
+		
+		if (f.startsWith?.("node:")) continue;
 		files.push(f);
 	}
 
+	console.log(`[DEBUG_RESOLVE] pickPrimaryBaseFile - Total stack frames: ${files.length}`);
+	console.log(`[DEBUG_RESOLVE] ALL stack frames:`);
+	for (let i = 0; i < files.length; i++) {
+		console.log(`[DEBUG_RESOLVE]   [${i}] ${files[i]}`);
+	}
+
 	let iSloth = -1;
 	for (let i = 0; i < files.length; i++) {
-		if (path.basename(files[i]).toLowerCase() === "slothlet.mjs") iSloth = i;
+		if (path.basename(files[i]).toLowerCase() === "slothlet.mjs") {
+			iSloth = i;
+		}
 	}
+
+	console.log(`[DEBUG_RESOLVE] Found slothlet.mjs at index: ${iSloth}, total files: ${files.length}`);
 	if (iSloth !== -1) {
-		const j = iSloth + 1;
-		if (j < files.length) {
-			const b = path.basename(files[j]).toLowerCase();
-			if (/^index\.(mjs|cjs|js)$/.test(b) && j + 1 < files.length) return files[j + 1];
-			return files[j];
+		console.log(`[DEBUG_RESOLVE] Files after slothlet.mjs:`);
+		for (let k = iSloth + 1; k < Math.min(files.length, iSloth + 5); k++) {
+			console.log(`[DEBUG_RESOLVE]   [${k}] ${files[k]}`);
 		}
 	}
-	return null;
+
+	if (iSloth !== -1) {
+		
+		let j = iSloth + 1;
+
+		
+function isSlothletInternalFile(filePath) {
+	if (!filePath) return true;
+
+	
+	if (filePath.includes(path.sep + "src" + path.sep + "lib" + path.sep)) return true;
+
+	
+	if (path.basename(filePath).toLowerCase() === "slothlet.mjs") return true;
+
+	
+	if (filePath.startsWith(THIS_DIR + path.sep)) return true;
+
+	return false;
 }
 
 
 function pickFallbackBaseFile() {
+	console.log("[DEBUG_RESOLVE] pickFallbackBaseFile called");
 	for (const cs of getStack(pickFallbackBaseFile)) {
 		const f = toFsPath(cs?.getFileName?.());
 		if (!f) continue;
-		if (f.startsWith?.("node:internal")) continue;
+		
+		if (f.startsWith?.("node:")) continue;
 		if (f === THIS_FILE) continue;
 		if (f.startsWith(THIS_DIR + path.sep)) continue; 
 		if (path.basename(f).toLowerCase() === "slothlet.mjs") continue;
+		if (isSlothletInternalFile(f)) {
+			console.log(`[DEBUG_RESOLVE] Fallback skipping internal file: ${f}`);
+			continue; 
+		}
+		console.log(`[DEBUG_RESOLVE] Fallback considering: ${f}`);
 		return f;
 	}
-	return THIS_FILE;
+	
+	
+	console.log(`[DEBUG_RESOLVE] Fallback: No user code found in stack, using process.cwd(): ${process.cwd()}`);
+	return process.cwd();
 }
 
 

package/dist/lib/helpers/sanitize.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/utilities.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/modes/slothlet_eager.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.
@@ -100,7 +100,35 @@ export async function create(dir, maxDepth = Infinity, currentDepth = 0) {
 	for (const entry of entries) {
 		if (entry.isDirectory() && !entry.name.startsWith(".") && currentDepth < maxDepth) {
 			const categoryPath = path.join(dir, entry.name);
-			api[this._toapiPathKey(entry.name)] = await this._loadCategory(categoryPath, currentDepth + 1, maxDepth);
+			const categoryKey = this._toapiPathKey(entry.name);
+			const categoryResult = await this._buildCategory(categoryPath, {
+				currentDepth: currentDepth + 1,
+				maxDepth,
+				mode: "eager",
+				existingApi: api 
+			});
+
+			
+			if (
+				api[categoryKey] &&
+				typeof api[categoryKey] === "object" &&
+				typeof categoryResult === "object" &&
+				!Array.isArray(api[categoryKey]) &&
+				!Array.isArray(categoryResult)
+			) {
+				if (this.config.debug) {
+					console.log(
+						`[DEBUG] eager: Merging subdirectory '${categoryKey}' - existing:`,
+						Object.keys(api[categoryKey]),
+						"new:",
+						Object.keys(categoryResult)
+					);
+				}
+				
+				Object.assign(api[categoryKey], categoryResult);
+			} else {
+				api[categoryKey] = categoryResult;
+			}
 		}
 	}
 

package/dist/lib/modes/slothlet_lazy.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.
@@ -161,7 +161,8 @@ export async function create(dir, maxDepth = Infinity, currentDepth = 0) {
 				depth,
 				maxDepth,
 				pathParts: [key],
-				runWithCtx
+				runWithCtx,
+				existingContent: parent[key] 
 			});
 			parent[key] = proxy;
 		}
@@ -173,6 +174,28 @@ export async function create(dir, maxDepth = Infinity, currentDepth = 0) {
 
 function replacePlaceholder(parent, key, placeholder, value, instance, depth) {
 	if (!parent || !key) return;
+
+	
+	if (
+		parent[key] !== placeholder &&
+		parent[key] &&
+		typeof parent[key] === "object" &&
+		typeof value === "object" &&
+		!Array.isArray(parent[key]) &&
+		!Array.isArray(value)
+	) {
+		if (instance?.config?.debug) {
+			console.log(`[lazy] MERGE CASE DETECTED for '${key}' - existing:`, Object.keys(parent[key]), "new:", Object.keys(value));
+			console.log(`[lazy] Before merge - parent[${key}]:`, parent[key]);
+		}
+		
+		Object.assign(parent[key], value);
+		if (instance?.config?.debug) {
+			console.log(`[lazy] After merge - parent[${key}]:`, Object.keys(parent[key]));
+		}
+		return;
+	}
+
 	if (parent[key] !== placeholder) return; 
 
 	
@@ -215,9 +238,43 @@ function replacePlaceholder(parent, key, placeholder, value, instance, depth) {
 	}
 
 	try {
-		Object.defineProperty(parent, finalKey, { value, writable: true, enumerable: true, configurable: true });
+		
+		if (
+			parent[finalKey] &&
+			typeof parent[finalKey] === "object" &&
+			typeof value === "object" &&
+			!Array.isArray(parent[finalKey]) &&
+			!Array.isArray(value)
+		) {
+			if (instance?.config?.debug) {
+				console.log(`[lazy] Merging subdirectory '${finalKey}' - existing:`, Object.keys(parent[finalKey]), "new:", Object.keys(value));
+			}
+			
+			Object.assign(parent[finalKey], value);
+		} else {
+			Object.defineProperty(parent, finalKey, { value, writable: true, enumerable: true, configurable: true });
+		}
 	} catch {
-		parent[finalKey] = value; 
+		
+		if (
+			parent[finalKey] &&
+			typeof parent[finalKey] === "object" &&
+			typeof value === "object" &&
+			!Array.isArray(parent[finalKey]) &&
+			!Array.isArray(value)
+		) {
+			if (instance?.config?.debug) {
+				console.log(
+					`[lazy] Merging subdirectory '${finalKey}' (fallback) - existing:`,
+					Object.keys(parent[finalKey]),
+					"new:",
+					Object.keys(value)
+				);
+			}
+			Object.assign(parent[finalKey], value);
+		} else {
+			parent[finalKey] = value; 
+		}
 	}
 	if (instance?.config?.debug) {
 		console.log(`[lazy][materialize] replaced ${key}${finalKey !== key ? ` -> ${finalKey}` : ""} (${typeof value})`);
@@ -228,7 +285,7 @@ function replacePlaceholder(parent, key, placeholder, value, instance, depth) {
 }
 
 
-function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth, pathParts, runWithCtx }) {
+function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth, pathParts, runWithCtx, existingContent }) {
 	let materialized = null;
 	let inFlight = null;
 
@@ -243,6 +300,7 @@ function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth,
 				currentDepth: depth,
 				maxDepth,
 				mode: "lazy",
+				existingApi: parent, 
 				subdirHandler: ({ subDirPath: nestedPath, key: nestedKey, categoryModules, currentDepth: cd, maxDepth: md }) =>
 					createFolderProxy({
 						subDirPath: nestedPath,
@@ -256,6 +314,29 @@ function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth,
 					})
 			});
 			materialized = value;
+
+			
+			if (
+				existingContent &&
+				typeof existingContent === "object" &&
+				typeof materialized === "object" &&
+				!Array.isArray(existingContent) &&
+				!Array.isArray(materialized)
+			) {
+				if (instance?.config?.debug) {
+					console.log(
+						`[lazy] Merging existing content with materialized subdirectory '${key}' - existing:`,
+						Object.keys(existingContent),
+						"new:",
+						Object.keys(materialized)
+					);
+				}
+				
+				materialized = Object.assign({}, existingContent, materialized);
+			} else if (existingContent && !materialized) {
+				
+				materialized = existingContent;
+			}
 			if (instance?.config?.debug) {
 				try {
 					const infoKeys = materialized && typeof materialized === "object" ? Object.keys(materialized) : [];
@@ -345,6 +426,11 @@ function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth,
 				return pathParts.length > 0 ? pathParts.join(".") : undefined;
 			}
 			
+			if (prop === "__metadata" || prop === "__sourceFolder") {
+				
+				return Reflect.get(_t, prop);
+			}
+			
 			if (materialized) {
 				if (materialized && (typeof materialized === "object" || typeof materialized === "function")) return materialized[prop];
 				return undefined;
@@ -485,6 +571,10 @@ function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth,
 			if (prop === "__materialized") {
 				return { configurable: true, enumerable: false, writable: true, value: materialized };
 			}
+			
+			if (prop === "__metadata" || prop === "__sourceFolder") {
+				return Reflect.getOwnPropertyDescriptor(lazy_lazyTarget, prop);
+			}
 			if (prop === "prototype") {
 				
 				return Object.getOwnPropertyDescriptor(lazy_lazyTarget, "prototype");

package/dist/lib/runtime/runtime-asynclocalstorage.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,6 +21,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import util from "node:util";
 import { enableAlsForEventEmitters } from "@cldmv/slothlet/helpers/als-eventemitter";
+import { metadataAPI } from "@cldmv/slothlet/helpers/metadata-api";
 
 const als = new AsyncLocalStorage();
 
@@ -565,3 +566,6 @@ export const context = runtime_createLiveBinding("context");
 export const reference = runtime_createLiveBinding("reference");
 
 
+export { metadataAPI };
+
+

package/dist/lib/runtime/runtime-livebindings.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.
@@ -25,6 +25,7 @@ import {
 	setActiveInstance,
 	getCurrentActiveInstanceId
 } from "@cldmv/slothlet/helpers/instance-manager";
+import { metadataAPI } from "@cldmv/slothlet/helpers/metadata-api";
 
 
 export const requestALS = new AsyncLocalStorage();
@@ -433,3 +434,6 @@ export const contextManager = {
 	set: setContext,
 	runWithCtx
 };
+
+
+export { metadataAPI };

package/dist/lib/runtime/runtime.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.
@@ -225,3 +225,14 @@ export const instanceId = (() => {
 })();
 
 export const sharedALS = getCurrentRuntime().sharedALS;
+
+
+export const metadataAPI = new Proxy(
+	{},
+	{
+		get(_, prop) {
+			const runtime = getCurrentRuntime();
+			return runtime.metadataAPI[prop];
+		}
+	}
+);

package/dist/slothlet.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.
@@ -75,6 +75,11 @@ let DEBUG = process.argv.includes("--slothletdebug")
 		: false;
 
 
+if (DEBUG && !process.env.SLOTHLET_DEBUG) {
+	process.env.SLOTHLET_DEBUG = "1";
+}
+
+
 export const self = {};
 
 
@@ -143,7 +148,17 @@ const slothletObject = {
 	reference: {},
 	mode: "singleton",
 	loaded: false,
-	config: { lazy: false, apiDepth: Infinity, debug: DEBUG, dir: null, sanitize: null, allowApiOverwrite: true },
+	config: {
+		lazy: false,
+		apiDepth: Infinity,
+		debug: DEBUG,
+		dir: null,
+		sanitize: null,
+		allowApiOverwrite: true,
+		enableModuleOwnership: false
+	},
+	
+	_moduleOwnership: new Map(), 
 	_dispose: null,
 	_boundAPIShutdown: null,
 	instanceId: null, 
@@ -391,7 +406,7 @@ const slothletObject = {
 
 	
 	async _buildCategory(categoryPath, options = {}) {
-		const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
+		const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler, existingApi } = options;
 
 		
 		return buildCategoryStructure(categoryPath, {
@@ -399,7 +414,8 @@ const slothletObject = {
 			maxDepth,
 			mode,
 			subdirHandler,
-			instance: this
+			instance: this,
+			existingApi
 		});
 	},
 
@@ -636,6 +652,17 @@ const slothletObject = {
 		}
 
 		
+		const instanceIdDesc = Object.getOwnPropertyDescriptor(boundApi, "instanceId");
+		if (!instanceIdDesc || instanceIdDesc.configurable) {
+			Object.defineProperty(boundApi, "instanceId", {
+				value: this.instanceId,
+				writable: false,
+				configurable: true,
+				enumerable: false
+			});
+		}
+
+		
 		const scopeDesc = Object.getOwnPropertyDescriptor(boundApi, "scope");
 		if (!scopeDesc || scopeDesc.configurable) {
 			Object.defineProperty(boundApi, "scope", {
@@ -678,8 +705,45 @@ const slothletObject = {
 	},
 
 	
-	async addApi(apiPath, folderPath) {
-		return addApiFromFolder({ apiPath, folderPath, instance: this });
+	_registerApiOwnership(apiPath, moduleId) {
+		if (!this.config.enableModuleOwnership) return;
+		this._moduleOwnership.set(apiPath, moduleId);
+		if (this.config.debug) {
+			console.log(`[DEBUG] Registered ownership: ${apiPath} -> ${moduleId}`);
+		}
+	},
+
+	
+	_getApiOwnership(apiPath) {
+		if (!this.config.enableModuleOwnership) return null;
+		return this._moduleOwnership.get(apiPath) || null;
+	},
+
+	
+	_validateModuleOwnership(apiPath, moduleId, forceOverwrite) {
+		if (!this.config.enableModuleOwnership || !forceOverwrite) return false;
+
+		const existingOwner = this._getApiOwnership(apiPath);
+		if (!existingOwner) {
+			
+			return true;
+		}
+
+		
+		if (existingOwner === moduleId) {
+			return true;
+		}
+
+		
+		if (this.config.debug) {
+			console.log(`[DEBUG] Ownership conflict: ${apiPath} owned by ${existingOwner}, attempted by ${moduleId}`);
+		}
+		return false;
+	},
+
+	
+	async addApi(apiPath, folderPath, metadata = {}, options = {}) {
+		return addApiFromFolder({ apiPath, folderPath, instance: this, metadata, options });
 	},