@cldmv/slothlet 2.8.0 → 2.9.0

package/dist/lib/helpers/api_builder.mjs

@@ -18,1575 +18,24 @@
 
 
 
-import fs from "node:fs/promises";
-import path from "node:path";
-import { types as utilTypes } from "node:util";
-import { pathToFileURL } from "node:url";
-import { multidefault_analyzeModules } from "@cldmv/slothlet/helpers/multidefault";
-import { setActiveInstance } from "@cldmv/slothlet/helpers/instance-manager";
 
+export {
+	isLikelySerializable,
+	analyzeModule,
+	processModuleFromAnalysis,
+	analyzeDirectoryStructure,
+	getCategoryBuildingDecisions
+} from "@cldmv/slothlet/helpers/api_builder/analysis";
 
+export {
+	getFlatteningDecision,
+	applyFunctionNamePreference,
+	processModuleForAPI,
+	buildCategoryDecisions
+} from "@cldmv/slothlet/helpers/api_builder/decisions";
 
+export { buildCategoryStructure, buildRootAPI, toapiPathKey, shouldIncludeFile } from "@cldmv/slothlet/helpers/api_builder/construction";
 
+export { safeDefine, deepMerge, mutateLiveBindingFunction } from "@cldmv/slothlet/helpers/utilities";
 
-
-function isLikelySerializable(val) {
-	const type = typeof val;
-
-	
-	if (type !== "object" || val === null) {
-		return type === "string" || type === "number" || type === "boolean" || type === "undefined";
-	}
-
-	
-	return (
-		Array.isArray(val) || val instanceof Date || val instanceof RegExp || val?.constructor === Object || typeof val.toJSON === "function" 
-	);
-}
-
-
-
-
-
-
-export async function analyzeModule(modulePath, options = {}) {
-	const { debug = false, instance = null } = options;
-
-	const moduleUrl = pathToFileURL(modulePath).href;
-
-	
-	let importUrl = moduleUrl;
-	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_runtime=${runtimeType}`;
-
-			
-			setActiveInstance(instance.instanceId);
-		}
-		
-		
-	}
-
-	const rawModule = await import(importUrl);
-
-	
-	let processedModule = rawModule;
-	const isCjs = modulePath.endsWith(".cjs") && "default" in rawModule;
-
-	if (isCjs) {
-		processedModule = rawModule.default;
-	}
-
-	const hasDefault = !!processedModule.default;
-	const isFunction = typeof processedModule.default === "function";
-	const exports = Object.entries(processedModule);
-	const namedExports = Object.entries(processedModule).filter(([k]) => k !== "default");
-
-	
-	let defaultExportType = null;
-	if (hasDefault) {
-		defaultExportType = typeof processedModule.default === "function" ? "function" : "object";
-	}
-
-	
-	let shouldWrapAsCallable = false;
-
-	
-	if (
-		hasDefault &&
-		typeof processedModule.default === "object" &&
-		processedModule.default !== null &&
-		typeof processedModule.default.default === "function"
-	) {
-		shouldWrapAsCallable = true;
-	}
-
-	
-	if (!shouldWrapAsCallable) {
-		for (const [_, exportValue] of namedExports) {
-			if (typeof exportValue === "object" && exportValue !== null && typeof exportValue.default === "function") {
-				shouldWrapAsCallable = true;
-				break;
-			}
-		}
-	}
-
-	if (debug) {
-		console.log(`[DEBUG] analyzeModule(${path.basename(modulePath)}):`, {
-			isCjs,
-			hasDefault,
-			isFunction,
-			defaultExportType,
-			shouldWrapAsCallable,
-			namedExportsCount: namedExports.length
-		});
-	}
-
-	return {
-		rawModule,
-		processedModule,
-		isFunction,
-		hasDefault,
-		isCjs,
-		exports,
-		defaultExportType,
-		shouldWrapAsCallable,
-		namedExports,
-		metadata: { modulePath }
-	};
-}
-
-
-export function processModuleFromAnalysis(analysis, options = {}) {
-	const { instance, debug = false } = options;
-	const { processedModule, isFunction, hasDefault, shouldWrapAsCallable, namedExports } = analysis;
-
-	if (!instance) {
-		throw new Error("processModuleFromAnalysis requires instance parameter for _toapiPathKey access");
-	}
-
-	
-	if (isFunction) {
-		let fn = processedModule.default;
-
-		
-		if (hasDefault) {
-			try {
-				Object.defineProperty(fn, "__slothletDefault", {
-					value: true,
-					writable: false,
-					enumerable: false,
-					configurable: true
-				});
-			} catch {
-				
-			}
-		}
-
-		
-		for (const [exportName, exportValue] of Object.entries(processedModule)) {
-			if (exportName !== "default") {
-				fn[instance._toapiPathKey(exportName)] = exportValue;
-			}
-		}
-		return fn;
-	}
-
-	
-	if (shouldWrapAsCallable) {
-		let callableObject = null;
-		let objectName = "callable";
-
-		
-		if (
-			hasDefault &&
-			typeof processedModule.default === "object" &&
-			processedModule.default !== null &&
-			typeof processedModule.default.default === "function"
-		) {
-			callableObject = processedModule.default;
-			objectName = processedModule.default.name || (namedExports[0] && namedExports[0][0] !== "default" ? namedExports[0][0] : "callable");
-		} else {
-			
-			for (const [exportName, exportValue] of namedExports) {
-				if (typeof exportValue === "object" && exportValue !== null && typeof exportValue.default === "function") {
-					callableObject = exportValue;
-					objectName = exportName;
-					break;
-				}
-			}
-		}
-
-		if (callableObject) {
-			const callableApi = {
-				[objectName]: function (...args) {
-					return callableObject.default.apply(callableObject, args);
-				}
-			}[objectName];
-
-			
-			for (const [methodName, method] of Object.entries(callableObject)) {
-				if (methodName === "default") continue;
-				callableApi[methodName] = method;
-			}
-
-			if (debug) {
-				console.log(`[DEBUG] Created callable wrapper for ${objectName}`);
-			}
-
-			return callableApi;
-		}
-	}
-
-	
-	if (hasDefault && typeof processedModule.default === "object") {
-		const obj = processedModule.default; 
-
-		
-		const namedExportsToAdd = Object.entries(processedModule).filter(
-			([exportName, exportValue]) => exportName !== "default" && exportValue !== obj
-		);
-
-		if (namedExportsToAdd.length > 0) {
-			
-			
-			const isCustomProxy = utilTypes?.isProxy?.(obj) ?? false;
-
-			if (isCustomProxy) {
-				
-				
-				for (const [exportName, exportValue] of namedExportsToAdd) {
-					const apiKey = instance._toapiPathKey(exportName);
-					obj[apiKey] = exportValue;
-				}
-
-				
-				
-				const proxyWithStructure = obj; 
-
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				proxyWithStructure.default = obj; 
-
-				
-				if (!proxyWithStructure.toJSON) {
-					Object.defineProperty(proxyWithStructure, "toJSON", {
-						value: function () {
-							
-							const serializable = {};
-
-							
-							for (const key of Reflect.ownKeys(this)) {
-								
-								if (typeof key !== "string") continue;
-
-								const descriptor = Reflect.getOwnPropertyDescriptor(this, key);
-								if (!descriptor || !descriptor.enumerable) continue;
-
-								if (key === "default") {
-									
-									continue;
-								}
-
-								const value = this[key];
-								if (typeof value === "function") {
-									serializable[key] = "[Function]";
-								} else if (isLikelySerializable(value)) {
-									
-									serializable[key] = value;
-								} else {
-									
-									try {
-										JSON.stringify(value);
-										serializable[key] = value;
-									} catch {
-										serializable[key] = "[Non-serializable value]";
-									}
-								}
-							}
-
-							
-							serializable._slothlet_proxy_info = {
-								type: "proxy",
-								circular_reference: "Property .default points to this object (excluded from serialization)",
-								warning: "This is a slothlet API proxy with circular .default reference"
-							};
-							return serializable;
-						},
-						writable: false,
-						enumerable: false,
-						configurable: true
-					});
-				}
-
-				
-				for (const [exportName, exportValue] of namedExportsToAdd) {
-					const apiKey = instance._toapiPathKey(exportName);
-					if (!(apiKey in proxyWithStructure)) {
-						proxyWithStructure[apiKey] = exportValue;
-					}
-				}
-
-				return proxyWithStructure;
-			} else {
-				
-				for (const [exportName, exportValue] of namedExportsToAdd) {
-					obj[instance._toapiPathKey(exportName)] = exportValue;
-				}
-
-				return obj;
-			}
-		}
-
-		return obj;
-	}
-
-	
-	if (namedExports.length > 0) {
-		const apiExport = {};
-		for (const [exportName, exportValue] of namedExports) {
-			apiExport[instance._toapiPathKey(exportName)] = exportValue;
-		}
-		return apiExport;
-	}
-
-	
-	throw new Error(`No valid exports found in processed module`);
-}
-
-
-export async function analyzeDirectoryStructure(categoryPath, options = {}) {
-	const { instance, currentDepth = 0, debug = false } = options;
-
-	if (!instance || typeof instance._toapiPathKey !== "function") {
-		throw new Error("analyzeDirectoryStructure requires a valid slothlet instance");
-	}
-
-	const files = await fs.readdir(categoryPath, { withFileTypes: true });
-	const moduleFiles = files.filter((f) => instance._shouldIncludeFile(f));
-	const categoryName = instance._toapiPathKey(path.basename(categoryPath));
-	const subDirs = files.filter((e) => e.isDirectory() && !e.name.startsWith("."));
-
-	
-	let processingStrategy;
-	if (moduleFiles.length === 0) {
-		processingStrategy = "empty";
-	} else if (moduleFiles.length === 1 && subDirs.length === 0) {
-		processingStrategy = "single-file";
-	} else {
-		processingStrategy = "multi-file";
-	}
-
-	
-	let multiDefaultAnalysis = null;
-	if (processingStrategy === "multi-file") {
-		multiDefaultAnalysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug, instance });
-	}
-
-	
-	const flatteningHints = {
-		shouldFlattenSingleFile: processingStrategy === "single-file",
-		shouldFlattenToParent: currentDepth > 0 && processingStrategy === "single-file",
-		hasMultipleDefaults: multiDefaultAnalysis?.hasMultipleDefaultExports || false,
-		selfReferentialFiles: multiDefaultAnalysis?.selfReferentialFiles || new Set()
-	};
-
-	if (debug) {
-		console.log(`[DEBUG] analyzeDirectoryStructure(${categoryName}):`, {
-			processingStrategy,
-			moduleCount: moduleFiles.length,
-			subDirCount: subDirs.length,
-			hasMultipleDefaults: flatteningHints.hasMultipleDefaults
-		});
-	}
-
-	return {
-		isSingleFile: processingStrategy === "single-file",
-		shouldAutoFlatten: flatteningHints.shouldFlattenSingleFile,
-		categoryName,
-		moduleFiles,
-		subDirs,
-		multiDefaultAnalysis,
-		processingStrategy,
-		flatteningHints
-	};
-}
-
-
-export async function getCategoryBuildingDecisions(categoryPath, options = {}) {
-	const { instance, currentDepth = 0, maxDepth = Infinity, debug = false } = options;
-
-	if (!instance) {
-		throw new Error("getCategoryBuildingDecisions requires a valid slothlet instance");
-	}
-
-	const analysis = await analyzeDirectoryStructure(categoryPath, { instance, currentDepth, maxDepth, debug });
-	const { processingStrategy, categoryName, moduleFiles, subDirs, multiDefaultAnalysis } = analysis;
-
-	const processedModules = [];
-	const subDirectories = [];
-
-	
-	if (processingStrategy !== "empty") {
-		for (const file of moduleFiles) {
-			const moduleExt = path.extname(file.name);
-			const moduleName = instance._toapiPathKey(path.basename(file.name, moduleExt));
-			const modulePath = path.join(categoryPath, file.name);
-
-			
-			const analysis = await analyzeModule(modulePath, {
-				debug,
-				instance
-			});
-			const processedModule = processModuleFromAnalysis(analysis, {
-				debug,
-				instance
-			});
-
-			
-			const flatteningInfo = {
-				shouldFlatten: false,
-				apiPathKey: moduleName,
-				reason: "default"
-			};
-
-			
-			if (processingStrategy === "single-file") {
-				
-				const functionNameMatchesFolder =
-					typeof processedModule === "function" &&
-					processedModule.name &&
-					processedModule.name.toLowerCase() === categoryName.toLowerCase();
-
-				const moduleNameMatchesCategory = moduleName === categoryName && typeof processedModule === "function" && currentDepth > 0;
-
-				if (functionNameMatchesFolder && currentDepth > 0) {
-					flatteningInfo.shouldFlatten = true;
-					flatteningInfo.apiPathKey = processedModule.name;
-					flatteningInfo.reason = "function name matches folder";
-				} else if (moduleNameMatchesCategory) {
-					flatteningInfo.shouldFlatten = true;
-					flatteningInfo.apiPathKey = categoryName;
-					flatteningInfo.reason = "module name matches category";
-				}
-			}
-
-			processedModules.push({
-				file,
-				moduleName,
-				processedModule,
-				flattening: flatteningInfo
-			});
-		}
-	}
-
-	
-	for (const subDirEntry of subDirs) {
-		if (currentDepth < maxDepth) {
-			const apiPathKey = instance._toapiPathKey(subDirEntry.name);
-			subDirectories.push({ dirEntry: subDirEntry, apiPathKey });
-		}
-	}
-
-	
-	const upwardFlatteningCandidate = { shouldFlatten: false, apiPathKey: null };
-	if (processedModules.length === 1 && subDirectories.length === 0) {
-		const single = processedModules[0];
-		if (single.moduleName === categoryName) {
-			upwardFlatteningCandidate.shouldFlatten = true;
-			upwardFlatteningCandidate.apiPathKey = single.moduleName;
-		}
-	}
-
-	if (debug) {
-		console.log(`[DEBUG] getCategoryBuildingDecisions(${categoryName}):`, {
-			processingStrategy,
-			moduleCount: processedModules.length,
-			subDirCount: subDirectories.length,
-			upwardFlattening: upwardFlatteningCandidate.shouldFlatten
-		});
-	}
-
-	return {
-		processingStrategy,
-		categoryName,
-		shouldFlattenSingle: processingStrategy === "single-file",
-		processedModules,
-		subDirectories,
-		multiDefaultAnalysis,
-		flatteningDecisions: analysis.flatteningHints,
-		upwardFlatteningCandidate
-	};
-}
-
-
-export function getFlatteningDecision(options) {
-	const {
-		mod,
-		fileName,
-		apiPathKey,
-		hasMultipleDefaultExports,
-		isSelfReferential,
-		
-		
-		moduleHasDefault = !!mod.default,
-		categoryName,
-		
-		totalModules = 1
-	} = options;
-
-	const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-
-	
-	if (isSelfReferential) {
-		return {
-			shouldFlatten: false,
-			flattenToRoot: false,
-			flattenToCategory: false,
-			preserveAsNamespace: true,
-			useAutoFlattening: false,
-			reason: "self-referential export"
-		};
-	}
-
-	
-	if (hasMultipleDefaultExports) {
-		if (moduleHasDefault) {
-			
-			return {
-				shouldFlatten: false,
-				flattenToRoot: false,
-				flattenToCategory: false,
-				preserveAsNamespace: true,
-				useAutoFlattening: false,
-				reason: "multi-default context with default export"
-			};
-		} else {
-			
-			return {
-				shouldFlatten: true,
-				flattenToRoot: true,
-				flattenToCategory: true,
-				preserveAsNamespace: false,
-				useAutoFlattening: false,
-				reason: "multi-default context without default export"
-			};
-		}
-	}
-
-	
-	if (moduleKeys.length === 1 && moduleKeys[0] === apiPathKey) {
-		return {
-			shouldFlatten: true,
-			flattenToRoot: false,
-			flattenToCategory: false,
-			preserveAsNamespace: false,
-			useAutoFlattening: true,
-			reason: "auto-flatten single named export matching filename"
-		};
-	}
-
-	
-	if (categoryName && fileName === categoryName && !moduleHasDefault && moduleKeys.length > 0) {
-		return {
-			shouldFlatten: true,
-			flattenToRoot: false,
-			flattenToCategory: true,
-			preserveAsNamespace: false,
-			useAutoFlattening: false,
-			reason: "filename matches container, flatten to category"
-		};
-	}
-
-	
-	
-	
-	
-	
-	
-	
-	
-	
-	
-	
-	
-	
-
-	
-	return {
-		shouldFlatten: false,
-		flattenToRoot: false,
-		flattenToCategory: false,
-		preserveAsNamespace: true,
-		useAutoFlattening: false,
-		reason: "traditional namespace preservation"
-	};
-}
-
-
-export function processModuleForAPI(options) {
-	const {
-		mod,
-		fileName,
-		apiPathKey,
-		hasMultipleDefaultExports,
-		isSelfReferential,
-		api,
-		getRootDefault,
-		setRootDefault,
-		context = {},
-		originalAnalysis = null
-	} = options;
-
-	const { debug = false, mode = "unknown", categoryName, totalModules = 1 } = context;
-
-	let processed = false;
-	let rootDefaultSet = false;
-	let flattened = false;
-	let namespaced = false;
-	const apiAssignments = {};
-
-	
-	
-	
-	const hasDefaultFunction = (mod && typeof mod.default === "function") || (mod && typeof mod === "function" && !mod.default);
-
-	
-	const defaultFunction = mod?.default || (typeof mod === "function" ? mod : null);
-
-	if (hasDefaultFunction) {
-		processed = true;
-
-		if (hasMultipleDefaultExports && !isSelfReferential) {
-			
-			apiAssignments[apiPathKey] = mod;
-			namespaced = true;
-
-			
-			
-
-			if (debug) {
-				console.log(
-					`[DEBUG] ${mode}: Multi-default function - using filename '${apiPathKey}' for default export, mod type: ${typeof mod}, function name: ${defaultFunction?.name}`
-				);
-			}
-		} else if (isSelfReferential) {
-			
-			apiAssignments[apiPathKey] = mod;
-			namespaced = true;
-
-			if (debug) {
-				console.log(`[DEBUG] ${mode}: Self-referential function - preserving ${fileName} as namespace`);
-			}
-		} else {
-			
-			if (debug) {
-				console.log(
-					`[DEBUG] ${mode}: Processing traditional default function: hasMultipleDefaultExports=${hasMultipleDefaultExports}, rootDefaultFunction=${!!(getRootDefault && getRootDefault())}`
-				);
-			}
-
-			
-			if (mode === "root" && getRootDefault && setRootDefault && !hasMultipleDefaultExports && !getRootDefault()) {
-				setRootDefault(defaultFunction);
-				rootDefaultSet = true;
-
-				if (debug) {
-					console.log(`[DEBUG] ${mode}: Set rootDefaultFunction to:`, defaultFunction.name);
-				}
-
-				
-				
-			} else {
-				
-				apiAssignments[apiPathKey] = mod;
-				namespaced = true;
-
-				
-				
-			}
-		}
-	} else {
-		
-		processed = true;
-
-		if (debug) {
-			console.log(`[DEBUG] ${mode}: Processing non-function or named-only exports for ${fileName}`);
-		}
-
-		
-		const decision = getFlatteningDecision({
-			mod,
-			fileName,
-			apiPathKey,
-			hasMultipleDefaultExports,
-			isSelfReferential,
-			
-			
-			
-			moduleHasDefault: originalAnalysis ? originalAnalysis.hasDefault : !!mod.default,
-			categoryName,
-			totalModules,
-			debug
-		});
-
-		if (debug) {
-			console.log(`[DEBUG] ${mode}: Flattening decision for ${fileName}: ${decision.reason}`);
-		}
-
-		if (decision.useAutoFlattening) {
-			
-			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-			apiAssignments[apiPathKey] = mod[moduleKeys[0]];
-			flattened = true;
-		} else if (decision.flattenToRoot || decision.flattenToCategory) {
-			
-			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-			for (const key of moduleKeys) {
-				apiAssignments[key] = mod[key];
-				if (debug) {
-					console.log(`[DEBUG] ${mode}: Flattened ${fileName}.${key} to ${decision.flattenToRoot ? "root" : "category"}.${key}`);
-				}
-			}
-			flattened = true;
-		} else if (isSelfReferential) {
-			
-			apiAssignments[apiPathKey] = mod[apiPathKey] || mod;
-			namespaced = true;
-		} else {
-			
-			apiAssignments[apiPathKey] = mod;
-			namespaced = true;
-		}
-	}
-
-	
-	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}'`);
-		}
-		api[key] = value;
-	}
-
-	return {
-		processed,
-		rootDefaultSet,
-		flattened,
-		namespaced,
-		apiAssignments
-	};
-}
-
-
-export function applyFunctionNamePreference(options) {
-	const { mod, fileName, apiPathKey, categoryModules, toapiPathKey, debug = false } = options;
-
-	let hasPreferredName = false;
-	let preferredKey = apiPathKey;
-
-	
-	for (const [, exportValue] of Object.entries(mod)) {
-		if (typeof exportValue === "function" && exportValue.name) {
-			const functionNameLower = exportValue.name.toLowerCase();
-			const filenameLower = fileName.toLowerCase();
-
-			
-			if (functionNameLower === filenameLower && exportValue.name !== apiPathKey) {
-				
-				preferredKey = exportValue.name;
-				hasPreferredName = true;
-
-				if (debug) {
-					console.log(`[DEBUG] Using function name preference: ${exportValue.name} instead of ${apiPathKey} for ${fileName}`);
-				}
-				break;
-			}
-
-			
-			const sanitizedFunctionName = toapiPathKey(exportValue.name);
-			if (sanitizedFunctionName.toLowerCase() === apiPathKey.toLowerCase() && exportValue.name !== apiPathKey) {
-				preferredKey = exportValue.name;
-				hasPreferredName = true;
-
-				if (debug) {
-					console.log(`[DEBUG] Using function name preference: ${exportValue.name} instead of ${apiPathKey} for ${fileName}`);
-				}
-				break;
-			}
-		}
-	}
-
-	if (hasPreferredName) {
-		
-		categoryModules[preferredKey] = mod;
-	}
-
-	return { hasPreferredName, preferredKey };
-}
-
-
-export async function buildCategoryStructure(categoryPath, options = {}) {
-	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler, instance } = options;
-
-	if (!instance || typeof instance._toapiPathKey !== "function" || typeof instance._shouldIncludeFile !== "function") {
-		throw new Error("buildCategoryStructure requires a valid slothlet instance");
-	}
-
-	const debug = instance.config?.debug || false;
-
-	if (debug) {
-		console.log(`[DEBUG] buildCategoryStructure called with path: ${categoryPath}, mode: ${mode}, depth: ${currentDepth}`);
-	}
-
-	const files = await fs.readdir(categoryPath, { withFileTypes: true });
-	const moduleFiles = files.filter((f) => instance._shouldIncludeFile(f));
-	const categoryName = instance._toapiPathKey(path.basename(categoryPath));
-	const subDirs = files.filter((e) => e.isDirectory() && !e.name.startsWith("."));
-
-	
-	if (moduleFiles.length === 1 && subDirs.length === 0) {
-		const moduleExt = path.extname(moduleFiles[0].name);
-		const moduleName = instance._toapiPathKey(path.basename(moduleFiles[0].name, moduleExt));
-
-		
-		const analysis = await analyzeModule(path.join(categoryPath, moduleFiles[0].name), {
-			debug,
-			instance
-		});
-
-		
-		const mod = processModuleFromAnalysis(analysis, { instance, debug });
-
-		
-		const functionNameMatchesFolder = typeof mod === "function" && mod.name && mod.name.toLowerCase() === categoryName.toLowerCase();
-
-		const functionNameMatchesFilename =
-			typeof mod === "function" &&
-			mod.name &&
-			instance._toapiPathKey(mod.name).toLowerCase() === instance._toapiPathKey(moduleName).toLowerCase() &&
-			mod.name !== instance._toapiPathKey(moduleName);
-
-		
-
-		
-		
-
-		
-		if (moduleName === categoryName && typeof mod === "function" && currentDepth > 0) {
-			try {
-				Object.defineProperty(mod, "name", { value: categoryName, configurable: true });
-			} catch {
-				
-			}
-			return mod;
-		}
-
-		
-		if (moduleName === categoryName && mod && typeof mod === "object" && !Array.isArray(mod) && currentDepth > 0) {
-			if (debug) {
-				console.log(`[DEBUG] Single-file auto-flattening: ${categoryName}/${moduleFiles[0].name} -> flatten object contents`);
-			}
-
-			
-			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-			if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
-				return mod[moduleName]; 
-			}
-
-			
-			
-			
-			
-			
-			
-			if (moduleKeys.length > 1) {
-				if (debug) {
-					console.log(`[DEBUG] Default export flattening: ${categoryName}/${moduleFiles[0].name} -> flatten default object contents`);
-				}
-				return mod; 
-			}
-			return mod;
-		}
-
-		
-		if (moduleFiles.length === 1 && currentDepth > 0 && mod && typeof mod === "object" && !Array.isArray(mod)) {
-			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-			const fileName = moduleFiles[0].name.replace(/\.(mjs|cjs|js)$/, "");
-
-			
-			const isGenericFilename = ["singlefile", "index", "main", "default"].includes(fileName.toLowerCase());
-
-			
-			if (moduleKeys.length === 1 && isGenericFilename) {
-				if (debug) {
-					console.log(
-						`[DEBUG] Single-file parent-level auto-flattening: ${categoryName}/${moduleFiles[0].name} -> flatten to parent level`
-					);
-				}
-				const exportValue = mod[moduleKeys[0]];
-				return { [moduleKeys[0]]: exportValue }; 
-			}
-		}
-
-		
-		if (functionNameMatchesFolder && currentDepth > 0) {
-			try {
-				Object.defineProperty(mod, "name", { value: mod.name, configurable: true });
-			} catch {
-				
-			}
-			return mod;
-		}
-
-		
-		if (functionNameMatchesFilename) {
-			return { [mod.name]: mod };
-		}
-
-		
-		if (typeof mod === "function" && (!mod.name || mod.name === "default" || mod.__slothletDefault === true) && currentDepth > 0) {
-			try {
-				Object.defineProperty(mod, "name", { value: categoryName, configurable: true });
-			} catch {
-				
-			}
-			return mod;
-		}
-
-		
-		const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-		if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
-			return mod[moduleName]; 
-		}
-
-		
-		return { [moduleName]: mod };
-	}
-
-	
-	const categoryModules = {};
-
-	
-	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug, instance });
-	const { totalDefaultExports, hasMultipleDefaultExports, selfReferentialFiles, defaultExportFiles: analysisDefaults } = analysis;
-
-	
-	const defaultExportFiles = [];
-	for (const { fileName } of analysisDefaults) {
-		const file = moduleFiles.find((f) => path.basename(f.name, path.extname(f.name)) === fileName);
-		if (file) {
-			const analysis = await analyzeModule(path.join(categoryPath, file.name), {
-				debug,
-				instance
-			});
-			const processedMod = processModuleFromAnalysis(analysis, {
-				debug,
-				instance
-			});
-			defaultExportFiles.push({ file, moduleName: instance._toapiPathKey(fileName), mod: processedMod, analysis });
-		}
-	}
-
-	if (debug) {
-		console.log(`[DEBUG] buildCategoryStructure: Multi-default analysis results`);
-		console.log(`[DEBUG]   - totalDefaultExports: ${totalDefaultExports}`);
-		console.log(`[DEBUG]   - hasMultipleDefaultExports: ${hasMultipleDefaultExports}`);
-		console.log(`[DEBUG]   - selfReferentialFiles: ${Array.from(selfReferentialFiles)}`);
-	}
-
-	
-	for (const file of moduleFiles) {
-		const moduleExt = path.extname(file.name);
-		const moduleName = instance._toapiPathKey(path.basename(file.name, moduleExt));
-		const fileName = path.basename(file.name, moduleExt);
-		const apiPathKey = instance._toapiPathKey(fileName);
-
-		
-		let mod = null;
-		let analysis = null;
-		const existingDefault = defaultExportFiles.find((def) => def.moduleName === moduleName);
-		if (existingDefault) {
-			mod = existingDefault.mod; 
-			analysis = existingDefault.analysis; 
-		} else {
-			analysis = await analyzeModule(path.join(categoryPath, file.name), {
-				debug,
-				instance
-			});
-			mod = processModuleFromAnalysis(analysis, {
-				debug,
-				instance
-			});
-		}
-
-		
-		processModuleForAPI({
-			mod,
-			fileName,
-			apiPathKey,
-			hasMultipleDefaultExports,
-			isSelfReferential: selfReferentialFiles.has(moduleName),
-			api: categoryModules,
-			getRootDefault: () => null, 
-			setRootDefault: () => {}, 
-			context: {
-				debug,
-				mode: "category",
-				categoryName,
-				totalModules: moduleFiles.length
-			},
-			originalAnalysis: analysis
-		});
-	}
-
-	
-	for (const subDirEntry of subDirs) {
-		if (currentDepth < maxDepth) {
-			const key = instance._toapiPathKey(subDirEntry.name);
-			const subDirPath = path.join(categoryPath, subDirEntry.name);
-			let subModule;
-
-			if (mode === "lazy" && typeof subdirHandler === "function") {
-				
-				subModule = subdirHandler({
-					subDirEntry,
-					subDirPath,
-					key,
-					categoryModules,
-					currentDepth,
-					maxDepth
-				});
-			} else {
-				
-				subModule = await buildCategoryStructure(subDirPath, {
-					currentDepth: currentDepth + 1,
-					maxDepth,
-					mode: "eager",
-					instance
-				});
-			}
-
-			
-			
-			if (
-				typeof subModule === "function" &&
-				subModule.name &&
-				subModule.name.toLowerCase() === key.toLowerCase() &&
-				subModule.name !== key
-			) {
-				categoryModules[subModule.name] = subModule; 
-			} else {
-				categoryModules[key] = subModule; 
-			}
-		}
-	}
-
-	return categoryModules;
-}
-
-
-export async function buildRootAPI(dir, options = {}) {
-	const { lazy = false, maxDepth = Infinity, instance } = options;
-
-	if (!instance || typeof instance._shouldIncludeFile !== "function" || typeof instance._loadCategory !== "function") {
-		throw new Error("buildRootAPI requires a valid slothlet instance");
-	}
-
-	const debug = instance.config?.debug || false;
-
-	if (debug) {
-		console.log(`[DEBUG] buildRootAPI called with dir: ${dir}, lazy: ${lazy}, maxDepth: ${maxDepth}`);
-	}
-
-	const entries = await fs.readdir(dir, { withFileTypes: true });
-	const api = {};
-	let rootDefaultFunction = null;
-
-	
-	const moduleFiles = entries.filter((e) => instance._shouldIncludeFile(e));
-
-	if (moduleFiles.length > 0) {
-		
-		const analysis = await multidefault_analyzeModules(moduleFiles, dir, { debug, instance });
-		const { hasMultipleDefaultExports, selfReferentialFiles } = analysis;
-
-		
-		for (const entry of moduleFiles) {
-			const ext = path.extname(entry.name);
-			const fileName = path.basename(entry.name, ext);
-			const apiPathKey = instance._toapiPathKey(fileName);
-
-			const analysis = await analyzeModule(path.join(dir, entry.name), {
-				debug,
-				instance
-			});
-			const mod = processModuleFromAnalysis(analysis, {
-				debug,
-				instance
-			});
-
-			
-			processModuleForAPI({
-				mod,
-				fileName,
-				apiPathKey,
-				hasMultipleDefaultExports,
-				isSelfReferential: selfReferentialFiles.has(fileName),
-				api,
-				getRootDefault: () => rootDefaultFunction,
-				setRootDefault: (fn) => {
-					rootDefaultFunction = fn;
-				},
-				context: {
-					debug,
-					mode: "root",
-					totalModules: moduleFiles.length
-				}
-			});
-		}
-	}
-
-	
-	for (const entry of entries) {
-		if (entry.isDirectory() && !entry.name.startsWith(".")) {
-			const categoryPath = path.join(dir, entry.name);
-
-			if (lazy) {
-				
-				api[instance._toapiPathKey(entry.name)] = await instance._loadCategory(categoryPath, 0, maxDepth);
-			} else {
-				
-				api[instance._toapiPathKey(entry.name)] = await buildCategoryStructure(categoryPath, {
-					currentDepth: 1,
-					maxDepth,
-					mode: "eager",
-					instance
-				});
-			}
-		}
-	}
-
-	
-	let finalApi;
-	if (debug) {
-		console.log(`[DEBUG] Final assembly: rootDefaultFunction=${!!rootDefaultFunction}`);
-		console.log(`[DEBUG] API object keys before final assembly:`, Object.keys(api));
-	}
-
-	if (rootDefaultFunction) {
-		
-		Object.assign(rootDefaultFunction, api);
-		finalApi = rootDefaultFunction;
-
-		if (debug) {
-			console.log(`[DEBUG] Applied root contributor pattern - final API is function`);
-		}
-	} else {
-		
-		finalApi = api;
-
-		if (debug) {
-			console.log(`[DEBUG] No root function - final API is object`);
-		}
-	}
-
-	return finalApi;
-}
-
-
-export async function buildCategoryDecisions(categoryPath, options = {}) {
-	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
-	const { instance } = options;
-
-	if (!instance || typeof instance._toapiPathKey !== "function") {
-		throw new Error("buildCategoryDecisions requires instance parameter with _toapiPathKey method");
-	}
-
-	const debug = instance.config?.debug || false;
-
-	
-	if (debug) {
-		console.log(`[DEBUG] buildCategoryDecisions called with path: ${categoryPath}, mode: ${mode}`);
-	}
-
-	const files = await fs.readdir(categoryPath, { withFileTypes: true });
-	const moduleFiles = files.filter((f) => instance._shouldIncludeFile(f));
-	const categoryName = instance._toapiPathKey(path.basename(categoryPath));
-	const subDirs = files.filter((e) => e.isDirectory() && !e.name.startsWith("."));
-
-	const decisions = {
-		type: null, 
-		categoryName,
-		moduleFiles,
-		subDirs,
-		currentDepth,
-		maxDepth,
-		mode,
-		subdirHandler,
-		
-		singleFile: null,
-		shouldFlatten: false,
-		flattenType: null, 
-		preferredName: null,
-		
-		multifileAnalysis: null,
-		processedModules: [],
-		categoryModules: {},
-		
-		subdirectoryDecisions: []
-	};
-
-	
-	if (moduleFiles.length === 1 && subDirs.length === 0) {
-		decisions.type = "single-file";
-		const moduleFile = moduleFiles[0];
-		const moduleExt = path.extname(moduleFile.name);
-		const moduleName = instance._toapiPathKey(path.basename(moduleFile.name, moduleExt));
-
-		decisions.singleFile = {
-			file: moduleFile,
-			moduleName,
-			moduleExt
-		};
-
-		
-		const analysis = await analyzeModule(path.join(categoryPath, moduleFile.name), {
-			debug,
-			instance
-		});
-		const mod = processModuleFromAnalysis(analysis, {
-			debug,
-			instance
-		});
-
-		decisions.singleFile.mod = mod;
-
-		
-		const functionNameMatchesFolder = typeof mod === "function" && mod.name && mod.name.toLowerCase() === categoryName.toLowerCase();
-
-		
-		const functionNameMatchesFilename =
-			typeof mod === "function" &&
-			mod.name &&
-			instance._toapiPathKey(mod.name).toLowerCase() === instance._toapiPathKey(moduleName).toLowerCase() &&
-			mod.name !== instance._toapiPathKey(moduleName);
-
-		
-		
-		if (moduleName === categoryName && typeof mod === "function" && currentDepth > 0) {
-			decisions.shouldFlatten = true;
-			decisions.flattenType = "function-folder-match";
-			decisions.preferredName = categoryName;
-			return decisions;
-		}
-
-		
-		
-		if (analysis.hasDefault && analysis.defaultExportType === "object" && moduleName === categoryName && currentDepth > 0) {
-			if (debug) {
-				console.log(`[DEBUG] Default export flattening: ${categoryName}/${moduleFile.name} -> flatten default object contents`);
-			}
-			decisions.shouldFlatten = true;
-			decisions.flattenType = "default-export-flatten";
-			return decisions;
-		}
-
-		
-		
-		if (moduleName === categoryName && mod && typeof mod === "object" && !Array.isArray(mod) && currentDepth > 0) {
-			
-			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-			if (debug) {
-				console.log(
-					`[DEBUG] Auto-flatten check: moduleName="${moduleName}" categoryName="${categoryName}" moduleKeys=[${moduleKeys}] match=${moduleKeys.length === 1 && moduleKeys[0] === moduleName}`
-				);
-			}
-			if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
-				if (debug) {
-					console.log(`[DEBUG] Single-file auto-flattening: ${categoryName}/${moduleFile.name} -> flatten object contents`);
-				}
-				decisions.shouldFlatten = true;
-				decisions.flattenType = "object-auto-flatten";
-				decisions.preferredName = moduleKeys[0]; 
-				return decisions;
-			}
-			
-			
-			
-			const fileBaseName = moduleFile.name.replace(/\.(mjs|cjs|js)$/, "");
-			if (fileBaseName === categoryName && moduleKeys.length > 0) {
-				if (debug) {
-					console.log(
-						`[DEBUG] Single-file filename-folder exact match flattening: ${categoryName}/${moduleFile.name} -> avoid double nesting`
-					);
-				}
-				decisions.shouldFlatten = true;
-				decisions.flattenType = "filename-folder-match-flatten";
-				return decisions;
-			}
-		}
-
-		
-		
-		
-		
-		if (moduleFiles.length === 1 && currentDepth > 0 && mod && typeof mod === "object" && !Array.isArray(mod)) {
-			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-			const fileName = moduleFile.name.replace(/\.(mjs|cjs|js)$/, "");
-
-			
-			
-			const isGenericFilename = ["singlefile", "index", "main", "default"].includes(fileName.toLowerCase());
-
-			
-			if (moduleKeys.length === 1 && isGenericFilename) {
-				if (debug) {
-					console.log(`[DEBUG] Single-file parent-level auto-flattening: ${categoryName}/${moduleFile.name} -> flatten to parent level`);
-				}
-				decisions.shouldFlatten = true;
-				decisions.flattenType = "parent-level-flatten";
-				decisions.preferredName = moduleKeys[0];
-				return decisions;
-			}
-		}
-
-		
-		
-		if (functionNameMatchesFolder && currentDepth > 0) {
-			decisions.shouldFlatten = true;
-			decisions.flattenType = "function-folder-match";
-			decisions.preferredName = mod.name;
-			return decisions;
-		}
-
-		
-		if (functionNameMatchesFilename) {
-			decisions.shouldFlatten = false;
-			decisions.preferredName = mod.name;
-			return decisions;
-		}
-
-		
-		
-		
-		if (
-			typeof mod === "function" &&
-			(!mod.name || mod.name === "default" || mod.__slothletDefault === true) && 
-			currentDepth > 0
-		) {
-			decisions.shouldFlatten = true;
-			decisions.flattenType = "default-function";
-			decisions.preferredName = categoryName;
-			return decisions;
-		}
-
-		
-		const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-		if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
-			
-			decisions.shouldFlatten = true;
-			decisions.flattenType = "object-auto-flatten";
-			decisions.preferredName = moduleName;
-			return decisions;
-		}
-
-		
-		decisions.shouldFlatten = false;
-		decisions.preferredName = moduleName;
-		return decisions;
-	}
-
-	
-	decisions.type = "multi-file";
-	if (debug) {
-		console.log(`[DEBUG] buildCategoryDecisions: Processing multi-file case for ${categoryPath}`);
-	}
-
-	
-	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug, instance });
-
-	decisions.multifileAnalysis = analysis;
-
-	const { totalDefaultExports, hasMultipleDefaultExports, selfReferentialFiles, defaultExportFiles: analysisDefaults } = analysis;
-
-	
-	const defaultExportFiles = [];
-	for (const { fileName } of analysisDefaults) {
-		const file = moduleFiles.find((f) => path.basename(f.name, path.extname(f.name)) === fileName);
-		if (file) {
-			const analysis = await analyzeModule(path.join(categoryPath, file.name), {
-				debug,
-				instance
-			});
-			const processedMod = processModuleFromAnalysis(analysis, {
-				debug,
-				instance
-			});
-			defaultExportFiles.push({ file, moduleName: instance._toapiPathKey(fileName), mod: processedMod, analysis });
-		}
-	}
-
-	if (debug) {
-		console.log(`[DEBUG] buildCategoryDecisions: Using shared multidefault utility results`);
-		console.log(`[DEBUG]   - totalDefaultExports: ${totalDefaultExports}`);
-		console.log(`[DEBUG]   - hasMultipleDefaultExports: ${hasMultipleDefaultExports}`);
-		console.log(`[DEBUG]   - selfReferentialFiles: ${Array.from(selfReferentialFiles)}`);
-	}
-
-	
-	for (const file of moduleFiles) {
-		const moduleExt = path.extname(file.name);
-		const moduleName = instance._toapiPathKey(path.basename(file.name, moduleExt));
-
-		
-		let mod = null;
-		let analysis = null;
-		const existingDefault = defaultExportFiles.find((def) => def.moduleName === moduleName);
-		if (existingDefault) {
-			mod = existingDefault.mod; 
-			
-			analysis = existingDefault.analysis;
-		} else {
-			
-			analysis = await analyzeModule(path.join(categoryPath, file.name), {
-				debug,
-				instance
-			});
-			mod = processModuleFromAnalysis(analysis, {
-				debug,
-				instance
-			});
-		}
-
-		const moduleDecision = {
-			file,
-			moduleName,
-			mod,
-			type: null, 
-			apiPathKey: null,
-			shouldFlatten: false,
-			flattenType: null,
-			specialHandling: null
-		};
-
-		if (moduleName === categoryName && mod && typeof mod === "object") {
-			moduleDecision.type = "category-match-object";
-			moduleDecision.specialHandling = "category-merge";
-		} else if (typeof mod === "function") {
-			moduleDecision.type = "function";
-
-			
-			const isSelfReferential = selfReferentialFiles.has(moduleName);
-
-			if (hasMultipleDefaultExports && mod.__slothletDefault === true && !isSelfReferential) {
-				
-				moduleDecision.apiPathKey = moduleName;
-				moduleDecision.specialHandling = "multi-default-filename";
-				if (debug) {
-					console.log(
-						`[DEBUG] Multi-default function case: ${moduleName} => ${moduleDecision.apiPathKey} (hasMultiple=${hasMultipleDefaultExports}, __slothletDefault=${mod.__slothletDefault}, isSelfRef=${isSelfReferential})`
-					);
-				}
-			} else if (selfReferentialFiles.has(moduleName)) {
-				
-				moduleDecision.type = "self-referential";
-				moduleDecision.specialHandling = "self-referential-namespace";
-			} else {
-				
-				const fnName = mod.name && mod.name !== "default" ? mod.name : moduleName;
-				if (debug) {
-					console.log(
-						`[DEBUG] Standard function case: ${moduleName}, fnName=${fnName}, mod.__slothletDefault=${mod.__slothletDefault}, hasMultiple=${hasMultipleDefaultExports}`
-					);
-				}
-
-				
-				
-				if (fnName && fnName.toLowerCase() === moduleName.toLowerCase() && fnName !== moduleName) {
-					
-					moduleDecision.apiPathKey = fnName;
-					moduleDecision.specialHandling = "prefer-function-name";
-				} else {
-					
-					moduleDecision.apiPathKey = instance._toapiPathKey(fnName);
-				}
-			}
-		} else {
-			moduleDecision.type = "object";
-
-			
-			let hasPreferredName = false;
-			const modWithPreferredNames = {};
-
-			for (const [exportName, exportValue] of Object.entries(mod)) {
-				if (
-					typeof exportValue === "function" &&
-					exportValue.name &&
-					instance._toapiPathKey(exportValue.name).toLowerCase() === instance._toapiPathKey(moduleName).toLowerCase() &&
-					exportValue.name !== instance._toapiPathKey(moduleName)
-				) {
-					
-					modWithPreferredNames[exportValue.name] = exportValue;
-					hasPreferredName = true;
-				} else {
-					modWithPreferredNames[instance._toapiPathKey(exportName)] = exportValue;
-				}
-			}
-
-			if (hasPreferredName) {
-				moduleDecision.specialHandling = "preferred-export-names";
-				moduleDecision.processedExports = modWithPreferredNames;
-			} else if (selfReferentialFiles.has(moduleName)) {
-				
-				moduleDecision.type = "self-referential";
-				moduleDecision.specialHandling = "self-referential-namespace";
-			} else {
-				
-				const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-				const apiPathKey = instance._toapiPathKey(moduleName);
-
-				
-				
-				if (!hasMultipleDefaultExports && analysis.hasDefault && analysis.defaultExportType === "object") {
-					moduleDecision.shouldFlatten = true;
-					moduleDecision.flattenType = "single-default-object";
-					moduleDecision.apiPathKey = apiPathKey;
-				} else if (hasMultipleDefaultExports && !analysis.hasDefault && moduleKeys.length > 0) {
-					
-					moduleDecision.shouldFlatten = true;
-					moduleDecision.flattenType = "multi-default-no-default";
-				} else if (moduleKeys.length === 1 && moduleKeys[0] === apiPathKey) {
-					
-					moduleDecision.shouldFlatten = true;
-					moduleDecision.flattenType = "single-named-export-match";
-					moduleDecision.apiPathKey = apiPathKey;
-				} else if (!analysis.hasDefault && moduleKeys.length > 0 && moduleName === categoryName) {
-					
-					moduleDecision.shouldFlatten = true;
-					moduleDecision.flattenType = "category-name-match-flatten";
-				} else {
-					
-					moduleDecision.apiPathKey = apiPathKey;
-				}
-			}
-		}
-
-		decisions.processedModules.push(moduleDecision);
-	}
-
-	
-	for (const subDir of subDirs) {
-		const subDirPath = path.join(categoryPath, subDir.name);
-		const subDirDecision = {
-			name: subDir.name,
-			path: subDirPath,
-			apiPathKey: instance._toapiPathKey(subDir.name),
-			shouldRecurse: currentDepth < maxDepth
-		};
-		decisions.subdirectoryDecisions.push(subDirDecision);
-	}
-
-	return decisions;
-}
+export { addApiFromFolder } from "@cldmv/slothlet/helpers/api_builder/add_api";