@cldmv/slothlet 2.11.0 → 3.0.1

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

@@ -1,553 +0,0 @@
-/*
-	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 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, metadata = {}, options = {} }) {
-	const { forceOverwrite = false, moduleId } = options;
-
-	
-	if (forceOverwrite && !moduleId) {
-		throw new Error(`[slothlet] Rule 12: forceOverwrite requires moduleId parameter for ownership tracking`);
-	}
-
-	if (forceOverwrite && !instance.config.enableModuleOwnership) {
-		throw new Error(`[slothlet] Rule 12: forceOverwrite requires enableModuleOwnership: true in slothlet configuration`);
-	}
-
-	if (!instance.loaded) {
-		throw new Error("[slothlet] Cannot add API: API not loaded. Call create() or load() first.");
-	}
-
-	
-	if (typeof apiPath !== "string") {
-		throw new TypeError("[slothlet] addApi: 'apiPath' must be a string.");
-	}
-	const normalizedApiPath = apiPath.trim();
-	if (normalizedApiPath === "") {
-		throw new TypeError("[slothlet] addApi: 'apiPath' must be a non-empty, non-whitespace string.");
-	}
-	const pathParts = normalizedApiPath.split(".");
-	if (pathParts.some((part) => part === "")) {
-		throw new Error(`[slothlet] addApi: 'apiPath' must not contain empty segments. Received: "${normalizedApiPath}"`);
-	}
-
-	
-	if (typeof folderPath !== "string") {
-		throw new TypeError("[slothlet] addApi: 'folderPath' must be a string.");
-	}
-
-	
-	
-	
-	let resolvedFolderPath = 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}`);
-		}
-	}
-
-	
-	let stats;
-	try {
-		stats = await fs.stat(resolvedFolderPath);
-	} catch (error) {
-		throw new Error(`[slothlet] addApi: Cannot access folder: ${resolvedFolderPath} - ${error.message}`);
-	}
-	if (!stats.isDirectory()) {
-		throw new Error(`[slothlet] addApi: Path is not a directory: ${resolvedFolderPath}`);
-	}
-
-	if (instance.config.debug) {
-		console.log(`[DEBUG] addApi: Loading modules from ${resolvedFolderPath} to path: ${normalizedApiPath}`);
-	}
-
-	
-	
-	
-
-	
-	let earlyCurrentTarget = instance.api;
-	let earlyCurrentBoundTarget = instance.boundapi;
-	const earlyPathParts = normalizedApiPath.split(".");
-
-	for (let i = 0; i < earlyPathParts.length - 1; i++) {
-		const part = earlyPathParts[i];
-		const key = instance._toapiPathKey(part);
-		if (earlyCurrentTarget[key]) {
-			earlyCurrentTarget = earlyCurrentTarget[key];
-		} else {
-			earlyCurrentTarget = null;
-			break;
-		}
-		if (earlyCurrentBoundTarget[key]) {
-			earlyCurrentBoundTarget = earlyCurrentBoundTarget[key];
-		} else {
-			earlyCurrentBoundTarget = null;
-			break;
-		}
-	}
-
-	const earlyFinalKey = instance._toapiPathKey(earlyPathParts[earlyPathParts.length - 1]);
-	let superEarlyExistingTargetContent = null;
-	let superEarlyExistingBoundContent = null;
-
-	if (earlyCurrentTarget && earlyCurrentTarget[earlyFinalKey]) {
-		if (typeof earlyCurrentTarget[earlyFinalKey] === "function" && earlyCurrentTarget[earlyFinalKey].__slothletPath) {
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: SUPER EARLY - Target is lazy proxy - materializing to capture existing content`);
-			}
-			const _ = earlyCurrentTarget[earlyFinalKey].__trigger;
-			await earlyCurrentTarget[earlyFinalKey]();
-		}
-		if (typeof earlyCurrentTarget[earlyFinalKey] === "object") {
-			superEarlyExistingTargetContent = { ...earlyCurrentTarget[earlyFinalKey] };
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: SUPER EARLY - Captured existing target content:`, Object.keys(superEarlyExistingTargetContent));
-			}
-		}
-	}
-
-	if (earlyCurrentBoundTarget && earlyCurrentBoundTarget[earlyFinalKey]) {
-		if (instance.config.debug) {
-			console.log(
-				`[DEBUG] addApi: SUPER EARLY - currentBoundTarget[${earlyFinalKey}] exists, type:`,
-				typeof earlyCurrentBoundTarget[earlyFinalKey]
-			);
-		}
-		if (typeof earlyCurrentBoundTarget[earlyFinalKey] === "function" && earlyCurrentBoundTarget[earlyFinalKey].__slothletPath) {
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: SUPER EARLY - Bound target is lazy proxy - materializing to capture existing bound content`);
-			}
-			const _ = earlyCurrentBoundTarget[earlyFinalKey].__trigger;
-			await earlyCurrentBoundTarget[earlyFinalKey]();
-		}
-		if (typeof earlyCurrentBoundTarget[earlyFinalKey] === "object") {
-			superEarlyExistingBoundContent = { ...earlyCurrentBoundTarget[earlyFinalKey] };
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: SUPER EARLY - Captured existing bound content:`, Object.keys(superEarlyExistingBoundContent));
-			}
-		}
-	}
-
-	
-	let newModules;
-	if (instance.config.lazy) {
-		
-		newModules = await instance.modes.lazy.create.call(instance, resolvedFolderPath, instance.config.apiDepth || Infinity, 0);
-	} else {
-		
-		newModules = await instance.modes.eager.create.call(instance, resolvedFolderPath, instance.config.apiDepth || Infinity, 0);
-	}
-
-	if (instance.config.debug) {
-		console.log(`[DEBUG] addApi: Loaded modules structure:`, Object.keys(newModules || {}));
-		console.log(`[DEBUG] addApi: Full newModules:`, newModules);
-	}
-
-	
-	
-	if (newModules && typeof newModules === "object" && newModules.addapi) {
-		if (instance.config.debug) {
-			console.log(`[DEBUG] addApi: Found addapi.mjs - applying Rule 6 flattening`);
-			console.log(`[DEBUG] addApi: Original structure:`, Object.keys(newModules));
-			console.log(`[DEBUG] addApi: Addapi contents:`, Object.keys(newModules.addapi));
-		}
-
-		
-		const addapiContent = newModules.addapi;
-
-		
-		delete newModules.addapi;
-
-		
-		if (addapiContent && typeof addapiContent === "object") {
-			
-			Object.assign(newModules, addapiContent);
-
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: After addapi flattening:`, Object.keys(newModules));
-			}
-		} else if (typeof addapiContent === "function") {
-			
-			Object.assign(newModules, addapiContent);
-
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: Flattened addapi function with properties:`, Object.keys(newModules));
-			}
-		}
-	}
-
-	
-	
-	
-	const pathSegments = normalizedApiPath.split(".");
-	const lastSegment = pathSegments[pathSegments.length - 1];
-	let rootLevelFileContent = null;
-
-	if (newModules && typeof newModules === "object" && newModules[lastSegment]) {
-		if (instance.config.debug) {
-			console.log(`[DEBUG] addApi: Found root-level file matching API path segment "${lastSegment}" - applying Rule 7 flattening`);
-		}
-
-		
-		let fileContent = newModules[lastSegment];
-		if (typeof fileContent === "function" && fileContent.name && fileContent.name.startsWith("lazyFolder_")) {
-			
-			if (fileContent.__slothletPath) {
-				const _ = fileContent.__trigger; 
-				await fileContent(); 
-				
-				fileContent = newModules[lastSegment]; 
-				if (instance.config.debug) {
-					console.log(`[DEBUG] addApi: Materialized lazy proxy for root-level file:`, Object.keys(fileContent || {}));
-				}
-			}
-		}
-
-		if (instance.config.debug) {
-			console.log(`[DEBUG] addApi: Root-level file content:`, Object.keys(fileContent || {}));
-		}
-
-		
-		
-		rootLevelFileContent = fileContent && typeof fileContent === "object" ? { ...fileContent } : fileContent;
-
-		
-		delete newModules[lastSegment];
-
-		if (instance.config.debug) {
-			console.log(`[DEBUG] addApi: After removing root-level file, remaining structure:`, Object.keys(newModules));
-		}
-	}
-
-	
-	
-	
-	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));
-		} else {
-			console.log(
-				`[DEBUG] addApi: Loaded modules (non-object):`,
-				typeof newModules === "function" ? `[Function: ${newModules.name || "anonymous"}]` : newModules
-			);
-		}
-	}
-
-	
-	let currentTarget = instance.api;
-	let currentBoundTarget = instance.boundapi;
-
-	for (let i = 0; i < pathParts.length - 1; i++) {
-		const part = pathParts[i];
-		const key = instance._toapiPathKey(part);
-
-		
-		
-		
-		if (Object.prototype.hasOwnProperty.call(currentTarget, key)) {
-			const existing = currentTarget[key];
-			if (existing === null || (typeof existing !== "object" && typeof existing !== "function")) {
-				throw new Error(
-					`[slothlet] Cannot extend API path "${normalizedApiPath}" through segment "${part}": ` +
-						`existing value is type "${typeof existing}", cannot add properties.`
-				);
-			}
-			
-			
-		} else {
-			currentTarget[key] = {};
-		}
-		if (Object.prototype.hasOwnProperty.call(currentBoundTarget, key)) {
-			const existingBound = currentBoundTarget[key];
-			if (existingBound === null || (typeof existingBound !== "object" && typeof existingBound !== "function")) {
-				throw new Error(
-					`[slothlet] Cannot extend bound API path "${normalizedApiPath}" through segment "${part}": ` +
-						`existing value is type "${typeof existingBound}", cannot add properties.`
-				);
-			}
-			
-		} else {
-			currentBoundTarget[key] = {};
-		}
-
-		
-		currentTarget = currentTarget[key];
-		currentBoundTarget = currentBoundTarget[key];
-	}
-
-	
-	const finalKey = instance._toapiPathKey(pathParts[pathParts.length - 1]);
-
-	if (instance.config.debug) {
-		console.log(`[DEBUG] addApi: Final assignment - newModules type:`, typeof newModules, "keys:", Object.keys(newModules || {}));
-	}
-
-	
-	
-	
-
-	
-	if (typeof newModules === "function") {
-		
-		
-		if (Object.prototype.hasOwnProperty.call(currentTarget, finalKey)) {
-			const existing = currentTarget[finalKey];
-
-			
-			if (instance.config.enableModuleOwnership && existing) {
-				const normalizedPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
-				const canOverwrite = instance._validateModuleOwnership(normalizedPath, moduleId, forceOverwrite);
-
-				if (forceOverwrite && !canOverwrite) {
-					const existingOwner = instance._getApiOwnership(normalizedPath);
-					throw new Error(
-						`[slothlet] Rule 12: Cannot overwrite API "${normalizedPath}" - owned by module "${existingOwner}", ` +
-							`attempted by module "${moduleId}". Modules can only overwrite APIs they own.`
-					);
-				}
-			}
-
-			
-			if (!forceOverwrite && instance.config.allowApiOverwrite === false) {
-				console.warn(
-					`[slothlet] Skipping addApi: API path "${normalizedApiPath}" final key "${finalKey}" ` +
-						`already exists (type: "${typeof existing}"). Set allowApiOverwrite: true to allow overwrites.`
-				);
-				return; 
-			}
-
-			
-			if (existing !== null && typeof existing !== "function") {
-				console.warn(
-					`[slothlet] Overwriting existing non-function value at API path "${normalizedApiPath}" ` +
-						`final key "${finalKey}" with a function. Previous type: "${typeof existing}".`
-				);
-			} else if (typeof existing === "function") {
-				
-				console.warn(
-					`[slothlet] Overwriting existing function at API path "${normalizedApiPath}" ` + `final key "${finalKey}" with a new function.`
-				);
-			}
-		}
-		currentTarget[finalKey] = newModules;
-		currentBoundTarget[finalKey] = newModules;
-	} else if (typeof newModules === "object" && newModules !== null) {
-		
-		if (Object.prototype.hasOwnProperty.call(currentTarget, finalKey)) {
-			const existing = currentTarget[finalKey];
-
-			
-			if (instance.config.enableModuleOwnership && existing) {
-				const normalizedPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
-				const canOverwrite = instance._validateModuleOwnership(normalizedPath, moduleId, forceOverwrite);
-
-				if (forceOverwrite && !canOverwrite) {
-					const existingOwner = instance._getApiOwnership(normalizedPath);
-					throw new Error(
-						`[slothlet] Rule 12: Cannot overwrite API "${normalizedPath}" - owned by module "${existingOwner}", ` +
-							`attempted by module "${moduleId}". Modules can only overwrite APIs they own.`
-					);
-				}
-			}
-
-			
-			if (!forceOverwrite && instance.config.allowApiOverwrite === false && existing !== undefined && existing !== null) {
-				
-				const hasContent = typeof existing === "object" ? Object.keys(existing).length > 0 : true;
-				if (hasContent) {
-					console.warn(
-						`[slothlet] Skipping addApi merge: API path "${normalizedApiPath}" final key "${finalKey}" ` +
-							`already exists with content (type: "${typeof existing}"). Set allowApiOverwrite: true to allow merging.`
-					);
-					return; 
-				}
-			}
-
-			if (existing !== null && typeof existing !== "object" && typeof existing !== "function") {
-				throw new Error(
-					`[slothlet] Cannot merge API at "${normalizedApiPath}": ` +
-						`existing value at final key "${finalKey}" is type "${typeof existing}", cannot merge into primitives.`
-				);
-			}
-		}
-		if (Object.prototype.hasOwnProperty.call(currentBoundTarget, finalKey)) {
-			const existingBound = currentBoundTarget[finalKey];
-			if (existingBound !== null && typeof existingBound !== "object" && typeof existingBound !== "function") {
-				throw new Error(
-					`[slothlet] Cannot merge bound API at "${normalizedApiPath}": ` +
-						`existing value at final key "${finalKey}" is type "${typeof existingBound}", cannot merge into primitives.`
-				);
-			}
-		}
-
-		
-		
-		
-		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] = {};
-		}
-		if (!currentBoundTarget[finalKey]) {
-			currentBoundTarget[finalKey] = {};
-		}
-
-		
-		
-		
-		
-		
-
-		
-		if (superEarlyExistingTargetContent) {
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: Restoring existing content - keys:`, Object.keys(superEarlyExistingTargetContent));
-			}
-			Object.assign(currentTarget[finalKey], superEarlyExistingTargetContent);
-		}
-		if (superEarlyExistingBoundContent) {
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: Restoring existing BOUND content - keys:`, Object.keys(superEarlyExistingBoundContent));
-			}
-			Object.assign(currentBoundTarget[finalKey], superEarlyExistingBoundContent);
-		}
-
-		
-		if (instance.config.debug) {
-			console.log(`[DEBUG] addApi: Before merging new modules - current keys:`, Object.keys(currentTarget[finalKey] || {}));
-			console.log(`[DEBUG] addApi: New modules to merge - keys:`, Object.keys(newModules));
-		}
-		Object.assign(currentTarget[finalKey], newModules);
-		Object.assign(currentBoundTarget[finalKey], newModules);
-		if (instance.config.debug) {
-			console.log(`[DEBUG] addApi: After merging new modules - keys:`, Object.keys(currentTarget[finalKey] || {}));
-		}
-
-		
-		if (rootLevelFileContent !== null) {
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: Merging root-level file content into API path "${normalizedApiPath}"`);
-				console.log(`[DEBUG] addApi: Root-level file functions:`, Object.keys(rootLevelFileContent));
-				console.log(`[DEBUG] addApi: Target before root-level merge:`, Object.keys(currentTarget[finalKey]));
-			}
-
-			
-			if (rootLevelFileContent && typeof rootLevelFileContent === "object") {
-				Object.assign(currentTarget[finalKey], rootLevelFileContent);
-				Object.assign(currentBoundTarget[finalKey], rootLevelFileContent);
-			} else if (typeof rootLevelFileContent === "function") {
-				
-				Object.assign(currentTarget[finalKey], rootLevelFileContent);
-				Object.assign(currentBoundTarget[finalKey], rootLevelFileContent);
-			}
-
-			if (instance.config.debug) {
-				console.log(`[DEBUG] addApi: After merging root-level file, final API structure:`, Object.keys(currentTarget[finalKey]));
-			}
-		}
-	} else if (newModules === null || newModules === undefined) {
-		
-		const receivedType = newModules === null ? "null" : "undefined";
-		console.warn(
-			`[slothlet] addApi: No modules loaded from folder at API path "${normalizedApiPath}". ` +
-				`Loaded modules resulted in ${receivedType}. Check that the folder contains valid module files.`
-		);
-	} else {
-		
-		
-		currentTarget[finalKey] = newModules;
-		currentBoundTarget[finalKey] = newModules;
-	}
-
-	
-	if (instance.config.debug) {
-		console.log(`[DEBUG] addApi: Before updateBindings - currentTarget[${finalKey}]:`, Object.keys(currentTarget[finalKey] || {}));
-		console.log(
-			`[DEBUG] addApi: Before updateBindings - currentBoundTarget[${finalKey}]:`,
-			Object.keys(currentBoundTarget[finalKey] || {})
-		);
-	}
-
-	
-	if (instance.config.enableModuleOwnership && moduleId) {
-		const fullApiPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
-		instance._registerApiOwnership(fullApiPath, moduleId);
-	}
-
-	instance.updateBindings(instance.context, instance.reference, instance.boundapi);
-	if (instance.config.debug) {
-		console.log(`[DEBUG] addApi: After updateBindings - api[${finalKey}]:`, Object.keys(instance.api[finalKey] || {}));
-	}
-
-	if (instance.config.debug) {
-		console.log(`[DEBUG] addApi: Successfully added modules at ${normalizedApiPath}`);
-	}
-}