kempo-server 3.0.7 → 3.0.9

package/dist/defaultConfig.js

@@ -1 +1 @@
-export default{allowedMimes:{html:{mime:"text/html",encoding:"utf8"},htm:{mime:"text/html",encoding:"utf8"},shtml:{mime:"text/html",encoding:"utf8"},css:{mime:"text/css",encoding:"utf8"},xml:{mime:"text/xml",encoding:"utf8"},gif:{mime:"image/gif",encoding:"binary"},jpeg:{mime:"image/jpeg",encoding:"binary"},jpg:{mime:"image/jpeg",encoding:"binary"},js:{mime:"application/javascript",encoding:"utf8"},mjs:{mime:"application/javascript",encoding:"utf8"},json:{mime:"application/json",encoding:"utf8"},webp:{mime:"image/webp",encoding:"binary"},png:{mime:"image/png",encoding:"binary"},svg:{mime:"image/svg+xml",encoding:"utf8"},svgz:{mime:"image/svg+xml",encoding:"utf8"},ico:{mime:"image/x-icon",encoding:"binary"},webm:{mime:"video/webm",encoding:"binary"},mp4:{mime:"video/mp4",encoding:"binary"},m4v:{mime:"video/mp4",encoding:"binary"},ogv:{mime:"video/ogg",encoding:"binary"},mp3:{mime:"audio/mpeg",encoding:"binary"},ogg:{mime:"audio/ogg",encoding:"binary"},wav:{mime:"audio/wav",encoding:"binary"},woff:{mime:"font/woff",encoding:"binary"},woff2:{mime:"font/woff2",encoding:"binary"},ttf:{mime:"font/ttf",encoding:"binary"},otf:{mime:"font/otf",encoding:"binary"},eot:{mime:"application/vnd.ms-fontobject",encoding:"binary"},pdf:{mime:"application/pdf",encoding:"binary"},txt:{mime:"text/plain",encoding:"utf8"},webmanifest:{mime:"application/manifest+json",encoding:"utf8"},md:{mime:"text/markdown",encoding:"utf8"},csv:{mime:"text/csv",encoding:"utf8"},doc:{mime:"application/msword",encoding:"binary"},docx:{mime:"application/vnd.openxmlformats-officedocument.wordprocessingml.document",encoding:"binary"},xls:{mime:"application/vnd.ms-excel",encoding:"binary"},xlsx:{mime:"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",encoding:"binary"},ppt:{mime:"application/vnd.ms-powerpoint",encoding:"binary"},pptx:{mime:"application/vnd.openxmlformats-officedocument.presentationml.presentation",encoding:"binary"},avif:{mime:"image/avif",encoding:"binary"},wasm:{mime:"application/wasm",encoding:"binary"}},disallowedRegex:["^/\\..*","\\.config\\.js$","\\.config\\.json$","\\.env$","\\.git/","\\.htaccess$","\\.htpasswd$","^/node_modules/","^/vendor/","\\.log$","\\.bak$","\\.sql$","\\.ini$","config\\.php$","wp-config\\.php$","\\.DS_Store$","package\\.json$","package-lock\\.json$","\\.template\\.html$","\\.fragment\\.html$","\\.page\\.html$"],routeFiles:["GET.js","POST.js","PUT.js","DELETE.js","HEAD.js","OPTIONS.js","PATCH.js","CONNECT.js","TRACE.js","index.js"],noRescanPaths:["^/\\.well-known/","/favicon\\.ico$","/robots\\.txt$","/sitemap\\.xml$","/apple-touch-icon","/android-chrome-","/browserconfig\\.xml$","/manifest\\.json$","\\.map$","/__webpack_hmr$","/hot-update\\.","/sockjs-node/"],maxRescanAttempts:3,customRoutes:{},middleware:{cors:{enabled:!1,origin:"*",methods:["GET","POST","PUT","DELETE","OPTIONS"],headers:["Content-Type","Authorization"]},compression:{enabled:!1,threshold:1024},rateLimit:{enabled:!1,maxRequests:100,windowMs:6e4,message:"Too many requests"},security:{enabled:!0,headers:{"X-Content-Type-Options":"nosniff","X-Frame-Options":"DENY","X-XSS-Protection":"1; mode=block"}},logging:{enabled:!0,includeUserAgent:!1,includeResponseTime:!0},custom:[]},maxBodySize:1048576,cache:{enabled:!1,maxSize:100,maxMemoryMB:50,ttlMs:3e5,maxHeapUsagePercent:70,memoryCheckInterval:3e4,watchFiles:!0,enableMemoryMonitoring:!0},templating:{preRender:!1,ssr:!1,ssrPriority:!1,globals:{},state:{},maxFragmentDepth:10}};
+export default{allowedMimes:{html:{mime:"text/html",encoding:"utf8"},htm:{mime:"text/html",encoding:"utf8"},shtml:{mime:"text/html",encoding:"utf8"},css:{mime:"text/css",encoding:"utf8"},xml:{mime:"text/xml",encoding:"utf8"},gif:{mime:"image/gif",encoding:"binary"},jpeg:{mime:"image/jpeg",encoding:"binary"},jpg:{mime:"image/jpeg",encoding:"binary"},js:{mime:"application/javascript",encoding:"utf8"},mjs:{mime:"application/javascript",encoding:"utf8"},json:{mime:"application/json",encoding:"utf8"},webp:{mime:"image/webp",encoding:"binary"},png:{mime:"image/png",encoding:"binary"},svg:{mime:"image/svg+xml",encoding:"utf8"},svgz:{mime:"image/svg+xml",encoding:"utf8"},ico:{mime:"image/x-icon",encoding:"binary"},webm:{mime:"video/webm",encoding:"binary"},mp4:{mime:"video/mp4",encoding:"binary"},m4v:{mime:"video/mp4",encoding:"binary"},ogv:{mime:"video/ogg",encoding:"binary"},mp3:{mime:"audio/mpeg",encoding:"binary"},ogg:{mime:"audio/ogg",encoding:"binary"},wav:{mime:"audio/wav",encoding:"binary"},woff:{mime:"font/woff",encoding:"binary"},woff2:{mime:"font/woff2",encoding:"binary"},ttf:{mime:"font/ttf",encoding:"binary"},otf:{mime:"font/otf",encoding:"binary"},eot:{mime:"application/vnd.ms-fontobject",encoding:"binary"},pdf:{mime:"application/pdf",encoding:"binary"},txt:{mime:"text/plain",encoding:"utf8"},webmanifest:{mime:"application/manifest+json",encoding:"utf8"},md:{mime:"text/markdown",encoding:"utf8"},csv:{mime:"text/csv",encoding:"utf8"},doc:{mime:"application/msword",encoding:"binary"},docx:{mime:"application/vnd.openxmlformats-officedocument.wordprocessingml.document",encoding:"binary"},xls:{mime:"application/vnd.ms-excel",encoding:"binary"},xlsx:{mime:"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",encoding:"binary"},ppt:{mime:"application/vnd.ms-powerpoint",encoding:"binary"},pptx:{mime:"application/vnd.openxmlformats-officedocument.presentationml.presentation",encoding:"binary"},avif:{mime:"image/avif",encoding:"binary"},wasm:{mime:"application/wasm",encoding:"binary"}},disallowedRegex:["^/\\..*","\\.config\\.js$","\\.config\\.json$","\\.env$","\\.git/","\\.htaccess$","\\.htpasswd$","^/node_modules/","^/vendor/","\\.log$","\\.bak$","\\.sql$","\\.ini$","config\\.php$","wp-config\\.php$","\\.DS_Store$","package\\.json$","package-lock\\.json$","\\.template\\.html$","\\.fragment\\.html$"],routeFiles:["GET.js","POST.js","PUT.js","DELETE.js","HEAD.js","OPTIONS.js","PATCH.js","CONNECT.js","TRACE.js","index.js","GET.page.html","POST.page.html","PUT.page.html","DELETE.page.html","HEAD.page.html","OPTIONS.page.html","PATCH.page.html","CONNECT.page.html","TRACE.page.html","index.page.html","CATCH.js","CATCH.page.html"],noRescanPaths:["^/\\.well-known/","/favicon\\.ico$","/robots\\.txt$","/sitemap\\.xml$","/apple-touch-icon","/android-chrome-","/browserconfig\\.xml$","/manifest\\.json$","\\.map$","/__webpack_hmr$","/hot-update\\.","/sockjs-node/"],maxRescanAttempts:3,customRoutes:{},middleware:{cors:{enabled:!1,origin:"*",methods:["GET","POST","PUT","DELETE","OPTIONS"],headers:["Content-Type","Authorization"]},compression:{enabled:!1,threshold:1024},rateLimit:{enabled:!1,maxRequests:100,windowMs:6e4,message:"Too many requests"},security:{enabled:!0,headers:{"X-Content-Type-Options":"nosniff","X-Frame-Options":"DENY","X-XSS-Protection":"1; mode=block"}},logging:{enabled:!0,includeUserAgent:!1,includeResponseTime:!0},custom:[]},maxBodySize:1048576,cache:{enabled:!1,maxSize:100,maxMemoryMB:50,ttlMs:3e5,maxHeapUsagePercent:70,memoryCheckInterval:3e4,watchFiles:!0,enableMemoryMonitoring:!0},templating:{preRender:!1,ssr:!1,ssrPriority:!1,globals:{},state:{},maxFragmentDepth:10}};

package/dist/findFile.js

@@ -1 +1 @@
-import path from"path";export default(files,rootPath,requestPath,method,log)=>{log(`Finding file for: ${method} ${requestPath}`,3);let normalizeRequestPath=requestPath.startsWith("/")?requestPath.slice(1):requestPath;normalizeRequestPath.endsWith("/")&&normalizeRequestPath.length>0&&(normalizeRequestPath=normalizeRequestPath.slice(0,-1));const requestSegments=normalizeRequestPath?normalizeRequestPath.split("/"):[];log(`Normalized request path: ${normalizeRequestPath}`,4),log(`Request segments: [${requestSegments.join(", ")}]`,4);const isDynamicSegment=segment=>segment.startsWith("[")&&segment.endsWith("]"),getParamName=segment=>segment.slice(1,-1),getRelativePath=filePath=>path.relative(rootPath,filePath).replace(/\\/g,"/"),exactMatch=files.find(file=>getRelativePath(file)===normalizeRequestPath);if(exactMatch)return log(`Found exact match: ${exactMatch}`,2),[exactMatch,{}];const isDirectoryRequest="/"===requestPath||requestPath.endsWith("/")||!path.extname(requestPath);if(isDirectoryRequest){log("Processing directory request",3);const dirPath=normalizeRequestPath||"",methodUpper=method.toUpperCase(),indexFiles=[`${methodUpper}.js`,`${methodUpper}.html`,"index.js","index.html"];log(`Looking for index files: [${indexFiles.join(", ")}]`,3);for(const indexFile of indexFiles){const indexPath=dirPath?`${dirPath}/${indexFile}`:indexFile,exactIndexMatch=files.find(file=>getRelativePath(file)===indexPath);if(exactIndexMatch)return log(`Found index file: ${exactIndexMatch}`,2),[exactIndexMatch,{}]}}log("Searching for dynamic routes...",3);const dynamicMatches=[];for(const file of files){const fileSegments=getRelativePath(file).split("/"),fileName=fileSegments[fileSegments.length-1],fileDirSegments=fileSegments.slice(0,-1);if(fileDirSegments.length!==requestSegments.length)continue;const pathParams={};let isMatch=!0;for(let i=0;i<fileDirSegments.length;i++){const fileSegment=fileDirSegments[i],requestSegment=requestSegments[i];if(isDynamicSegment(fileSegment)){const paramName=getParamName(fileSegment);pathParams[paramName]=requestSegment,log(`Dynamic match: [${paramName}] = ${requestSegment}`,4)}else if(fileSegment!==requestSegment){isMatch=!1;break}}if(isMatch)if(isDirectoryRequest){const methodUpper=method.toUpperCase(),priority=[`${methodUpper}.js`,`${methodUpper}.html`,"index.js","index.html"].indexOf(fileName);-1!==priority&&(log(`Found dynamic directory match: ${file} (priority: ${priority})`,3),dynamicMatches.push({file:file,pathParams:pathParams,priority:priority}))}else log(`Found dynamic file match: ${file}`,3),dynamicMatches.push({file:file,pathParams:pathParams,priority:0})}if(dynamicMatches.length>0){dynamicMatches.sort((a,b)=>a.priority-b.priority);const bestMatch=dynamicMatches[0];return log(`Best dynamic match: ${bestMatch.file} with params: ${JSON.stringify(bestMatch.pathParams)}`,2),[bestMatch.file,bestMatch.pathParams]}return log(`No file found for: ${requestPath}`,3),[!1,{}]};
+import path from"path";export default(files,rootPath,requestPath,method,log)=>{log(`Finding file for: ${method} ${requestPath}`,3);let normalizeRequestPath=requestPath.startsWith("/")?requestPath.slice(1):requestPath;normalizeRequestPath.endsWith("/")&&normalizeRequestPath.length>0&&(normalizeRequestPath=normalizeRequestPath.slice(0,-1));const requestSegments=normalizeRequestPath?normalizeRequestPath.split("/"):[];log(`Normalized request path: ${normalizeRequestPath}`,4),log(`Request segments: [${requestSegments.join(", ")}]`,4);const isDynamicSegment=segment=>segment.startsWith("[")&&segment.endsWith("]"),getParamName=segment=>segment.slice(1,-1),getRelativePath=filePath=>path.relative(rootPath,filePath).replace(/\\/g,"/"),exactMatch=files.find(file=>getRelativePath(file)===normalizeRequestPath);if(exactMatch)return log(`Found exact match: ${exactMatch}`,2),[exactMatch,{}];const isDirectoryRequest="/"===requestPath||requestPath.endsWith("/")||!path.extname(requestPath);if(isDirectoryRequest){log("Processing directory request",3);const dirPath=normalizeRequestPath||"",methodUpper=method.toUpperCase(),indexFiles=[`${methodUpper}.js`,`${methodUpper}.html`,`${methodUpper}.page.html`,"index.js","index.html","index.page.html","CATCH.js","CATCH.html","CATCH.page.html"];log(`Looking for index files: [${indexFiles.join(", ")}]`,3);for(const indexFile of indexFiles){const indexPath=dirPath?`${dirPath}/${indexFile}`:indexFile,exactIndexMatch=files.find(file=>getRelativePath(file)===indexPath);if(exactIndexMatch)return log(`Found index file: ${exactIndexMatch}`,2),[exactIndexMatch,{}]}}log("Searching for dynamic routes...",3);const dynamicMatches=[];for(const file of files){const fileSegments=getRelativePath(file).split("/"),fileName=fileSegments[fileSegments.length-1],fileDirSegments=fileSegments.slice(0,-1);if(fileDirSegments.length!==requestSegments.length)continue;const pathParams={};let isMatch=!0;for(let i=0;i<fileDirSegments.length;i++){const fileSegment=fileDirSegments[i],requestSegment=requestSegments[i];if(isDynamicSegment(fileSegment)){const paramName=getParamName(fileSegment);pathParams[paramName]=requestSegment,log(`Dynamic match: [${paramName}] = ${requestSegment}`,4)}else if(fileSegment!==requestSegment){isMatch=!1;break}}if(isMatch)if(isDirectoryRequest){const methodUpper=method.toUpperCase(),priority=[`${methodUpper}.js`,`${methodUpper}.html`,`${methodUpper}.page.html`,"index.js","index.html","index.page.html","CATCH.js","CATCH.html","CATCH.page.html"].indexOf(fileName);-1!==priority&&(log(`Found dynamic directory match: ${file} (priority: ${priority})`,3),dynamicMatches.push({file:file,pathParams:pathParams,priority:priority}))}else log(`Found dynamic file match: ${file}`,3),dynamicMatches.push({file:file,pathParams:pathParams,priority:0})}if(dynamicMatches.length>0){dynamicMatches.sort((a,b)=>a.priority-b.priority);const bestMatch=dynamicMatches[0];return log(`Best dynamic match: ${bestMatch.file} with params: ${JSON.stringify(bestMatch.pathParams)}`,2),[bestMatch.file,bestMatch.pathParams]}return log(`No file found for: ${requestPath}`,3),[!1,{}]};

package/dist/router.js

@@ -1 +1 @@
-import path from"path";import{readFile,stat,readdir}from"fs/promises";import{pathToFileURL}from"url";import defaultConfig from"./defaultConfig.js";import getFiles from"./getFiles.js";import findFile from"./findFile.js";import serveFile from"./serveFile.js";import MiddlewareRunner from"./middlewareRunner.js";import ModuleCache from"./moduleCache.js";import createRequestWrapper,{readRawBody,parseBody}from"./requestWrapper.js";import createResponseWrapper from"./responseWrapper.js";import{corsMiddleware,compressionMiddleware,rateLimitMiddleware,securityMiddleware,loggingMiddleware}from"./builtinMiddleware.js";import{onRescan}from"./rescan.js";import{renderDir,renderPage}from"./templating/index.js";export default async(flags,log)=>{log("Initializing router",3);const rootPath=path.isAbsolute(flags.root)?flags.root:path.join(process.cwd(),flags.root);log(`Root path: ${rootPath}`,3);let config=defaultConfig;try{const configFileName=flags.config||".config.js",configPath=path.isAbsolute(configFileName)?configFileName:path.join(rootPath,configFileName);if(log(`Config file name: ${configFileName}`,3),log(`Config path: ${configPath}`,3),path.isAbsolute(configFileName))log("Config file name is absolute, skipping validation",4);else{const relativeConfigPath=path.relative(rootPath,configPath);if(log(`Relative config path: ${relativeConfigPath}`,4),log(`Starts with '..': ${relativeConfigPath.startsWith("..")}`,4),relativeConfigPath.startsWith("..")||path.isAbsolute(relativeConfigPath))throw log("Validation failed - throwing error",4),new Error(`Config file must be within the server root directory. Config path: ${configPath}, Root path: ${rootPath}`);log("Validation passed",4)}let userConfig;if(log(`Loading config from: ${configPath}`,3),configPath.endsWith(".js")){const configUrl=pathToFileURL(configPath).href+`?t=${Date.now()}`;userConfig=(await import(configUrl)).default}else{const configContent=await readFile(configPath,"utf8");userConfig=JSON.parse(configContent)}if(!userConfig)throw new Error("Config file is empty or has no default export");config={...defaultConfig,...userConfig,allowedMimes:{...defaultConfig.allowedMimes,...userConfig.allowedMimes||{}},middleware:{...defaultConfig.middleware,...userConfig.middleware||{}},customRoutes:{...defaultConfig.customRoutes,...userConfig.customRoutes||{}},cache:{...defaultConfig.cache,...userConfig.cache||{}},templating:{...defaultConfig.templating,...userConfig.templating||{}}},log("User config loaded and merged with defaults",3)}catch(e){if(e.message.includes("Config file must be within the server root directory"))throw e;const configFileName=flags.config||".config.js";if(configFileName.endsWith(".js"))try{const jsonFallback=configFileName.replace(/\.js$/,".json"),jsonPath=path.isAbsolute(jsonFallback)?jsonFallback:path.join(rootPath,jsonFallback);log(`Trying JSON fallback: ${jsonPath}`,3);const configContent=await readFile(jsonPath,"utf8"),userConfig=JSON.parse(configContent);config={...defaultConfig,...userConfig,allowedMimes:{...defaultConfig.allowedMimes,...userConfig.allowedMimes||{}},middleware:{...defaultConfig.middleware,...userConfig.middleware||{}},customRoutes:{...defaultConfig.customRoutes,...userConfig.customRoutes||{}},cache:{...defaultConfig.cache,...userConfig.cache||{}},templating:{...defaultConfig.templating,...userConfig.templating||{}}},log("User config loaded from JSON fallback",3)}catch(e2){log("Using default config (no config file found)",3)}else log("Using default config (no config file found)",3)}const dis=new Set(config.disallowedRegex);if(dis.add("^/\\..*"),dis.add("\\.config\\.js$"),dis.add("\\.config\\.json$"),dis.add("\\.git/"),config.disallowedRegex=[...dis],log(`Config loaded with ${config.disallowedRegex.length} disallowed patterns`,3),config.templating.preRender){const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,count=await renderDir(rootPath,rootPath,globals,state,maxFragmentDepth);log(`Pre-rendered ${count} page(s)`,2);for(const[urlPattern,dirPath]of Object.entries(config.customRoutes||{})){const baseDirRaw=dirPath.includes("*")?dirPath.split("*")[0]:dirPath,resolvedBaseDir=(path.isAbsolute(baseDirRaw)?baseDirRaw:path.resolve(rootPath,baseDirRaw)).replace(/[/\\]+$/,"");try{if(!(await stat(resolvedBaseDir)).isDirectory())continue;const extraCount=await renderDir(resolvedBaseDir,resolvedBaseDir,globals,state,maxFragmentDepth);log(`Pre-rendered ${extraCount} page(s) from custom route: ${urlPattern}`,2)}catch{}}}let files=await getFiles(rootPath,config,log);log(`Initial scan found ${files.length} files`,2),onRescan(async done=>{try{files=await getFiles(rootPath,config,log),log(`Rescan found ${files.length} files`,2),done(null,files.length)}catch(error){log(`Rescan failed: ${error.message}`,1),done(error)}});const middlewareRunner=new MiddlewareRunner;if(config.middleware?.cors?.enabled&&(middlewareRunner.use(corsMiddleware(config.middleware.cors)),log("CORS middleware enabled",3)),config.middleware?.compression?.enabled&&(middlewareRunner.use(compressionMiddleware(config.middleware.compression)),log("Compression middleware enabled",3)),config.middleware?.rateLimit?.enabled&&(middlewareRunner.use(rateLimitMiddleware(config.middleware.rateLimit)),log("Rate limit middleware enabled",3)),config.middleware?.security?.enabled&&(middlewareRunner.use(securityMiddleware(config.middleware.security)),log("Security middleware enabled",3)),config.middleware?.logging?.enabled&&(middlewareRunner.use(loggingMiddleware(config.middleware.logging,log)),log("Logging middleware enabled",3)),config.middleware?.custom&&config.middleware.custom.length>0){log(`Loading ${config.middleware.custom.length} custom middleware files`,3);for(const middlewarePath of config.middleware.custom)try{const resolvedPath=path.isAbsolute(middlewarePath)?middlewarePath:path.resolve(rootPath,middlewarePath),middlewareUrl=pathToFileURL(resolvedPath).href+`?t=${Date.now()}`,customMiddleware=(await import(middlewareUrl)).default;"function"==typeof customMiddleware?(middlewareRunner.use(customMiddleware(config.middleware)),log(`Custom middleware loaded: ${middlewarePath}`,3)):log(`Custom middleware error: ${middlewarePath} does not export a default function`,1)}catch(error){log(`Custom middleware error for ${middlewarePath}: ${error.message}`,1)}}let moduleCache=null;config.cache?.enabled&&(moduleCache=new ModuleCache(config.cache),log(`Module cache initialized: ${config.cache.maxSize} max modules, ${config.cache.maxMemoryMB}MB limit, ${config.cache.ttlMs}ms TTL`,2));const customRoutes=new Map,wildcardRoutes=new Map;if(config.customRoutes&&Object.keys(config.customRoutes).length>0){log(`Processing ${Object.keys(config.customRoutes).length} custom routes`,3);for(const[urlPath,filePath]of Object.entries(config.customRoutes))if(urlPath.includes("*")){const resolvedPath=path.isAbsolute(filePath)?filePath:path.resolve(rootPath,filePath);wildcardRoutes.set(urlPath,resolvedPath),log(`Wildcard route mapped: ${urlPath} -> ${resolvedPath}`,3)}else{const resolvedPath=path.isAbsolute(filePath)?filePath:path.resolve(rootPath,filePath);customRoutes.set(urlPath,resolvedPath),log(`Custom route mapped: ${urlPath} -> ${resolvedPath}`,3)}}const matchWildcardRoute=(requestPath,pattern)=>{const regexPattern=(pattern.startsWith("/")?pattern:"/"+pattern).replace(/\*\*/g,"(.+)").replace(/\*/g,"([^/]+)");return new RegExp(`^${regexPattern}$`).exec(requestPath)},serveStaticCustomFile=async(filePath,res)=>{const fileExtension=path.extname(filePath).toLowerCase().slice(1),mimeConfig=config.allowedMimes[fileExtension];let mimeType,encoding;"string"==typeof mimeConfig?(mimeType=mimeConfig,encoding=mimeType.startsWith("text/")?"utf8":void 0):(mimeType=mimeConfig?.mime||"application/octet-stream",encoding="utf8"===mimeConfig?.encoding?"utf8":void 0);const fileContent=await readFile(filePath,encoding);log(`Serving custom file as ${mimeType} (${fileContent.length} bytes)`,2);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;res.writeHead(200,{"Content-Type":contentType}),res.end(fileContent)},executeRouteModule=async(filePath,req,res,params={})=>{let module;if(moduleCache&&config.cache?.enabled){const fileStats=await stat(filePath);if(module=moduleCache.get(filePath,fileStats),!module){const fileUrl=pathToFileURL(filePath).href+`?t=${Date.now()}`;module=await import(fileUrl);const estimatedSizeKB=fileStats.size/1024;moduleCache.set(filePath,module,fileStats,estimatedSizeKB)}}else{const fileUrl=pathToFileURL(filePath).href+`?t=${Date.now()}`;module=await import(fileUrl)}if("function"!=typeof module.default)return log(`Route file does not export a function: ${filePath}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),void res.end("Route file does not export a function");const enhancedReq=createRequestWrapper(req,params),enhancedRes=createResponseWrapper(res),rawBody=await readRawBody(req);enhancedReq._rawBody=rawBody,enhancedReq.body=parseBody(rawBody,req.headers["content-type"]),moduleCache&&(enhancedReq._kempoCache=moduleCache),await module.default(enhancedReq,enhancedRes)},walkDynamic=async(base,segments)=>{if(0===segments.length)return{filePath:base,params:{}};const[head,...rest]=segments;let entries;try{entries=await readdir(base,{withFileTypes:!0})}catch{return null}for(const entry of entries)if(entry.name===head)if(entry.isDirectory()){const result=await walkDynamic(path.join(base,head),rest);if(result)return result}else if(entry.isFile()&&0===rest.length)return{filePath:path.join(base,head),params:{}};for(const entry of entries){if(!entry.isDirectory()||!entry.name.startsWith("[")||!entry.name.endsWith("]"))continue;const paramName=entry.name.slice(1,-1),result=await walkDynamic(path.join(base,entry.name),rest);if(result)return{filePath:result.filePath,params:{[paramName]:head,...result.params}}}return null},serveResolvedPath=async(filePath,fileStat,params,req,res)=>{if(fileStat.isDirectory()){const methodUpper=req.method.toUpperCase(),candidates=[`${methodUpper}.js`,`${methodUpper}.html`,"index.js","index.html","index.htm"];for(const candidate of candidates){const candidatePath=path.join(filePath,candidate);try{await stat(candidatePath)}catch{continue}return config.routeFiles.includes(candidate)?(log(`Executing route file: ${candidatePath}`,2),await executeRouteModule(candidatePath,req,res,params),!0):(log(`Serving index file: ${candidatePath}`,2),await serveStaticCustomFile(candidatePath,res),!0)}return null}const fileName=path.basename(filePath);return config.routeFiles.includes(fileName)?(log(`Executing route file: ${filePath}`,2),await executeRouteModule(filePath,req,res,params),!0):(await serveStaticCustomFile(filePath,res),!0)},serveCustomRoutePath=async(resolvedFilePath,req,res,customRootDir=null)=>{let fileStat;try{fileStat=await stat(resolvedFilePath);const result=await serveResolvedPath(resolvedFilePath,fileStat,{},req,res);if(result)return result}catch(e){if("ENOENT"!==e.code)throw e}if(!fileStat){let current=resolvedFilePath;const remaining=[];for(;current!==path.dirname(current);){remaining.unshift(path.basename(current)),current=path.dirname(current);try{if(!(await stat(current)).isDirectory())break;const result=await walkDynamic(current,remaining);if(!result)break;const resolvedStat=await stat(result.filePath),served=await serveResolvedPath(result.filePath,resolvedStat,result.params,req,res);if(served)return served;break}catch(e2){if("ENOENT"!==e2.code)throw e2}}}if(config.templating?.ssr&&customRootDir){const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,base=resolvedFilePath.replace(/\.html$/,"").replace(/[\/\\]+$/,"");for(const pageFile of[base+".page.html",path.join(base,"index.page.html")])try{await stat(pageFile);const html=await renderPage(pageFile,customRootDir,globals,state,maxFragmentDepth);return res.writeHead(200,{"Content-Type":"text/html; charset=utf-8"}),res.end(html),log(`SSR rendered custom route: ${pageFile}`,2),!0}catch(e){log(`SSR custom route miss for ${pageFile}: ${e.message}`,3)}}return null},rescanAttempts=new Map,dynamicNoRescanPaths=new Set,shouldSkipRescan=requestPath=>config.noRescanPaths.some(pattern=>new RegExp(pattern).test(requestPath))?(log(`Skipping rescan for configured pattern: ${requestPath}`,3),!0):!!dynamicNoRescanPaths.has(requestPath)&&(log(`Skipping rescan for dynamically blacklisted path: ${requestPath}`,3),!0),handler=async(req,res)=>{if(parseInt(req.headers["content-length"]||"0",10)>config.maxBodySize)return res.writeHead(413,{"Content-Type":"text/plain"}),void res.end("Payload Too Large");const rawBody=await new Promise((resolve,reject)=>{if(["GET","HEAD"].includes(req.method)&&!req.headers["content-length"])return resolve("");let body="",size=0;req.on("data",chunk=>{if(size+=chunk.length,size>config.maxBodySize)return req.destroy(),void reject(new Error("Payload Too Large"));body+=chunk.toString()}),req.on("end",()=>resolve(body)),req.on("error",reject)}).catch(err=>{if("Payload Too Large"===err.message)return res.writeHead(413,{"Content-Type":"text/plain"}),res.end("Payload Too Large"),null;throw err});if(null===rawBody)return;req._bufferedBody=rawBody;const enhancedRequest=createRequestWrapper(req,{}),enhancedResponse=createResponseWrapper(res);enhancedRequest._rawBody=rawBody,enhancedRequest.body=parseBody(rawBody,req.headers["content-type"]),await middlewareRunner.run(enhancedRequest,enhancedResponse,async()=>{const requestPath=enhancedRequest.url.split("?")[0];log(`${enhancedRequest.method} ${requestPath}`,4),log(`customRoutes keys: ${Array.from(customRoutes.keys()).join(", ")}`,4);const normalizePath=p=>{try{let np=decodeURIComponent(p);return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np}catch(e){log(`Warning: Failed to decode URI component "${p}": ${e.message}`,1);let np=p;return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np}},normalizedRequestPath=normalizePath(requestPath);log(`Normalized requestPath: ${normalizedRequestPath}`,4);let matchedKey=null;for(const key of customRoutes.keys())if(normalizePath(key)===normalizedRequestPath){matchedKey=key;break}if(matchedKey){const customFilePath=customRoutes.get(matchedKey);log(`Serving custom route: ${normalizedRequestPath} -> ${customFilePath}`,3);try{if(await serveCustomRoutePath(customFilePath,req,res,customFilePath))return;return log(`Custom route path not found: ${customFilePath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),void res.end("Custom route file not found")}catch(error){return log(`Error serving custom route ${normalizedRequestPath}: ${error.message}`,1),res.writeHead(500,{"Content-Type":"text/plain"}),void res.end("Internal Server Error")}}const wildcardMatch=(requestPath=>{for(const[pattern,filePath]of wildcardRoutes){const matches=matchWildcardRoute(requestPath,pattern);if(matches)return{filePath:filePath,matches:matches}}return null})(requestPath);if(wildcardMatch){const resolvedFilePath=((filePath,matches)=>{let resolvedPath=filePath,matchIndex=1;for(;resolvedPath.includes("**")&&matchIndex<matches.length;)resolvedPath=resolvedPath.replace("**",matches[matchIndex]),matchIndex++;for(;resolvedPath.includes("*")&&matchIndex<matches.length;)resolvedPath=resolvedPath.replace("*",matches[matchIndex]),matchIndex++;return path.isAbsolute(resolvedPath)?resolvedPath:path.resolve(rootPath,resolvedPath)})(wildcardMatch.filePath,wildcardMatch.matches);log(`Serving wildcard route: ${requestPath} -> ${resolvedFilePath}`,3);try{const customRootDir=wildcardMatch.filePath.split("*")[0].replace(/[\/\\]+$/,"");if(await serveCustomRoutePath(resolvedFilePath,req,res,customRootDir))return;log(`Wildcard route path not found: ${requestPath}`,2)}catch(error){return log(`Error serving wildcard route ${requestPath}: ${error.message}`,1),enhancedResponse.writeHead(500,{"Content-Type":"text/plain"}),void enhancedResponse.end("Internal Server Error")}}const served=await serveFile(files,rootPath,requestPath,req.method,config,req,res,log,moduleCache);if(!served&&config.maxRescanAttempts>0&&!shouldSkipRescan(requestPath)){log("File not found, rescanning directory...",1),files=await getFiles(rootPath,config,log),log(`Rescan found ${files.length} files`,2);await serveFile(files,rootPath,requestPath,req.method,config,req,res,log,moduleCache)?rescanAttempts.delete(requestPath):((requestPath=>{const newAttempts=(rescanAttempts.get(requestPath)||0)+1;rescanAttempts.set(requestPath,newAttempts),newAttempts>config.maxRescanAttempts&&(dynamicNoRescanPaths.add(requestPath),log(`Path ${requestPath} added to dynamic blacklist after ${newAttempts} failed attempts`,1)),log(`Rescan attempt ${newAttempts}/${config.maxRescanAttempts} for: ${requestPath}`,3)})(requestPath),log(`404 - File not found after rescan: ${requestPath}`,1),enhancedResponse.writeHead(404,{"Content-Type":"text/plain"}),enhancedResponse.end("Not Found"))}else served||(shouldSkipRescan(requestPath)?log(`404 - Skipped rescan for: ${requestPath}`,2):log(`404 - File not found: ${requestPath}`,1),enhancedResponse.writeHead(404,{"Content-Type":"text/plain"}),enhancedResponse.end("Not Found"))})};return handler.moduleCache=moduleCache,handler.getStats=()=>moduleCache?.getStats()||null,handler.logCacheStats=()=>moduleCache?.logStats(log),handler.clearCache=()=>moduleCache?.clear(),handler};
+import path from"path";import{readFile,stat,readdir}from"fs/promises";import{pathToFileURL}from"url";import defaultConfig from"./defaultConfig.js";import getFiles from"./getFiles.js";import findFile from"./findFile.js";import serveFile from"./serveFile.js";import MiddlewareRunner from"./middlewareRunner.js";import ModuleCache from"./moduleCache.js";import createRequestWrapper,{readRawBody,parseBody}from"./requestWrapper.js";import createResponseWrapper from"./responseWrapper.js";import{corsMiddleware,compressionMiddleware,rateLimitMiddleware,securityMiddleware,loggingMiddleware}from"./builtinMiddleware.js";import{onRescan}from"./rescan.js";import{renderDir,renderPage}from"./templating/index.js";export default async(flags,log)=>{log("Initializing router",3);const rootPath=path.isAbsolute(flags.root)?flags.root:path.join(process.cwd(),flags.root);log(`Root path: ${rootPath}`,3);let config=defaultConfig;try{const configFileName=flags.config||".config.js",configPath=path.isAbsolute(configFileName)?configFileName:path.join(rootPath,configFileName);if(log(`Config file name: ${configFileName}`,3),log(`Config path: ${configPath}`,3),path.isAbsolute(configFileName))log("Config file name is absolute, skipping validation",4);else{const relativeConfigPath=path.relative(rootPath,configPath);if(log(`Relative config path: ${relativeConfigPath}`,4),log(`Starts with '..': ${relativeConfigPath.startsWith("..")}`,4),relativeConfigPath.startsWith("..")||path.isAbsolute(relativeConfigPath))throw log("Validation failed - throwing error",4),new Error(`Config file must be within the server root directory. Config path: ${configPath}, Root path: ${rootPath}`);log("Validation passed",4)}let userConfig;if(log(`Loading config from: ${configPath}`,3),configPath.endsWith(".js")){const configUrl=pathToFileURL(configPath).href+`?t=${Date.now()}`;userConfig=(await import(configUrl)).default}else{const configContent=await readFile(configPath,"utf8");userConfig=JSON.parse(configContent)}if(!userConfig)throw new Error("Config file is empty or has no default export");config={...defaultConfig,...userConfig,allowedMimes:{...defaultConfig.allowedMimes,...userConfig.allowedMimes||{}},middleware:{...defaultConfig.middleware,...userConfig.middleware||{}},customRoutes:{...defaultConfig.customRoutes,...userConfig.customRoutes||{}},cache:{...defaultConfig.cache,...userConfig.cache||{}},templating:{...defaultConfig.templating,...userConfig.templating||{}}},log("User config loaded and merged with defaults",3)}catch(e){if(e.message.includes("Config file must be within the server root directory"))throw e;const configFileName=flags.config||".config.js";if(configFileName.endsWith(".js"))try{const jsonFallback=configFileName.replace(/\.js$/,".json"),jsonPath=path.isAbsolute(jsonFallback)?jsonFallback:path.join(rootPath,jsonFallback);log(`Trying JSON fallback: ${jsonPath}`,3);const configContent=await readFile(jsonPath,"utf8"),userConfig=JSON.parse(configContent);config={...defaultConfig,...userConfig,allowedMimes:{...defaultConfig.allowedMimes,...userConfig.allowedMimes||{}},middleware:{...defaultConfig.middleware,...userConfig.middleware||{}},customRoutes:{...defaultConfig.customRoutes,...userConfig.customRoutes||{}},cache:{...defaultConfig.cache,...userConfig.cache||{}},templating:{...defaultConfig.templating,...userConfig.templating||{}}},log("User config loaded from JSON fallback",3)}catch(e2){log("Using default config (no config file found)",3)}else log("Using default config (no config file found)",3)}const dis=new Set(config.disallowedRegex);if(dis.add("^/\\..*"),dis.add("\\.config\\.js$"),dis.add("\\.config\\.json$"),dis.add("\\.git/"),config.disallowedRegex=[...dis],log(`Config loaded with ${config.disallowedRegex.length} disallowed patterns`,3),config.templating.preRender){const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,count=await renderDir(rootPath,rootPath,globals,state,maxFragmentDepth);log(`Pre-rendered ${count} page(s)`,2);for(const[urlPattern,dirPath]of Object.entries(config.customRoutes||{})){const baseDirRaw=dirPath.includes("*")?dirPath.split("*")[0]:dirPath,resolvedBaseDir=(path.isAbsolute(baseDirRaw)?baseDirRaw:path.resolve(rootPath,baseDirRaw)).replace(/[/\\]+$/,"");try{if(!(await stat(resolvedBaseDir)).isDirectory())continue;const extraCount=await renderDir(resolvedBaseDir,resolvedBaseDir,globals,state,maxFragmentDepth);log(`Pre-rendered ${extraCount} page(s) from custom route: ${urlPattern}`,2)}catch{}}}let files=await getFiles(rootPath,config,log);log(`Initial scan found ${files.length} files`,2),onRescan(async done=>{try{files=await getFiles(rootPath,config,log),log(`Rescan found ${files.length} files`,2),done(null,files.length)}catch(error){log(`Rescan failed: ${error.message}`,1),done(error)}});const middlewareRunner=new MiddlewareRunner;if(config.middleware?.cors?.enabled&&(middlewareRunner.use(corsMiddleware(config.middleware.cors)),log("CORS middleware enabled",3)),config.middleware?.compression?.enabled&&(middlewareRunner.use(compressionMiddleware(config.middleware.compression)),log("Compression middleware enabled",3)),config.middleware?.rateLimit?.enabled&&(middlewareRunner.use(rateLimitMiddleware(config.middleware.rateLimit)),log("Rate limit middleware enabled",3)),config.middleware?.security?.enabled&&(middlewareRunner.use(securityMiddleware(config.middleware.security)),log("Security middleware enabled",3)),config.middleware?.logging?.enabled&&(middlewareRunner.use(loggingMiddleware(config.middleware.logging,log)),log("Logging middleware enabled",3)),config.middleware?.custom&&config.middleware.custom.length>0){log(`Loading ${config.middleware.custom.length} custom middleware files`,3);for(const middlewarePath of config.middleware.custom)try{const resolvedPath=path.isAbsolute(middlewarePath)?middlewarePath:path.resolve(rootPath,middlewarePath),middlewareUrl=pathToFileURL(resolvedPath).href+`?t=${Date.now()}`,customMiddleware=(await import(middlewareUrl)).default;"function"==typeof customMiddleware?(middlewareRunner.use(customMiddleware(config.middleware)),log(`Custom middleware loaded: ${middlewarePath}`,3)):log(`Custom middleware error: ${middlewarePath} does not export a default function`,1)}catch(error){log(`Custom middleware error for ${middlewarePath}: ${error.message}`,1)}}let moduleCache=null;config.cache?.enabled&&(moduleCache=new ModuleCache(config.cache),log(`Module cache initialized: ${config.cache.maxSize} max modules, ${config.cache.maxMemoryMB}MB limit, ${config.cache.ttlMs}ms TTL`,2));const customRoutes=new Map,wildcardRoutes=new Map;if(config.customRoutes&&Object.keys(config.customRoutes).length>0){log(`Processing ${Object.keys(config.customRoutes).length} custom routes`,3);for(const[urlPath,filePath]of Object.entries(config.customRoutes))if(urlPath.includes("*")){const resolvedPath=path.isAbsolute(filePath)?filePath:path.resolve(rootPath,filePath);wildcardRoutes.set(urlPath,resolvedPath),log(`Wildcard route mapped: ${urlPath} -> ${resolvedPath}`,3)}else{const resolvedPath=path.isAbsolute(filePath)?filePath:path.resolve(rootPath,filePath);customRoutes.set(urlPath,resolvedPath),log(`Custom route mapped: ${urlPath} -> ${resolvedPath}`,3)}}const matchWildcardRoute=(requestPath,pattern)=>{const regexPattern=(pattern.startsWith("/")?pattern:"/"+pattern).replace(/\*\*/g,"(.+)").replace(/\*/g,"([^/]+)");return new RegExp(`^${regexPattern}$`).exec(requestPath)},serveStaticCustomFile=async(filePath,res)=>{const fileExtension=path.extname(filePath).toLowerCase().slice(1),mimeConfig=config.allowedMimes[fileExtension];let mimeType,encoding;"string"==typeof mimeConfig?(mimeType=mimeConfig,encoding=mimeType.startsWith("text/")?"utf8":void 0):(mimeType=mimeConfig?.mime||"application/octet-stream",encoding="utf8"===mimeConfig?.encoding?"utf8":void 0);const fileContent=await readFile(filePath,encoding);log(`Serving custom file as ${mimeType} (${fileContent.length} bytes)`,2);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;res.writeHead(200,{"Content-Type":contentType}),res.end(fileContent)},executeRouteModule=async(filePath,req,res,params={})=>{let module;if(moduleCache&&config.cache?.enabled){const fileStats=await stat(filePath);if(module=moduleCache.get(filePath,fileStats),!module){const fileUrl=pathToFileURL(filePath).href+`?t=${Date.now()}`;module=await import(fileUrl);const estimatedSizeKB=fileStats.size/1024;moduleCache.set(filePath,module,fileStats,estimatedSizeKB)}}else{const fileUrl=pathToFileURL(filePath).href+`?t=${Date.now()}`;module=await import(fileUrl)}if("function"!=typeof module.default)return log(`Route file does not export a function: ${filePath}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),void res.end("Route file does not export a function");const enhancedReq=createRequestWrapper(req,params),enhancedRes=createResponseWrapper(res),rawBody=await readRawBody(req);enhancedReq._rawBody=rawBody,enhancedReq.body=parseBody(rawBody,req.headers["content-type"]),moduleCache&&(enhancedReq._kempoCache=moduleCache),await module.default(enhancedReq,enhancedRes)},walkDynamic=async(base,segments)=>{if(0===segments.length)return{filePath:base,params:{}};const[head,...rest]=segments;let entries;try{entries=await readdir(base,{withFileTypes:!0})}catch{return null}for(const entry of entries)if(entry.name===head)if(entry.isDirectory()){const result=await walkDynamic(path.join(base,head),rest);if(result)return result}else if(entry.isFile()&&0===rest.length)return{filePath:path.join(base,head),params:{}};for(const entry of entries){if(!entry.isDirectory()||!entry.name.startsWith("[")||!entry.name.endsWith("]"))continue;const paramName=entry.name.slice(1,-1),result=await walkDynamic(path.join(base,entry.name),rest);if(result)return{filePath:result.filePath,params:{[paramName]:head,...result.params}}}return null},serveResolvedPath=async(filePath,fileStat,params,req,res)=>{if(fileStat.isDirectory()){const methodUpper=req.method.toUpperCase(),candidates=[`${methodUpper}.js`,`${methodUpper}.html`,`${methodUpper}.page.html`,"index.js","index.html","index.page.html","index.htm","CATCH.js","CATCH.html","CATCH.page.html"];for(const candidate of candidates){const candidatePath=path.join(filePath,candidate);try{await stat(candidatePath)}catch{continue}if(candidate.endsWith(".page.html")){log(`Rendering page template: ${candidatePath}`,2);const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,html=await renderPage(candidatePath,rootPath,globals,state,maxFragmentDepth);return res.writeHead(200,{"Content-Type":"text/html; charset=utf-8"}),res.end(html),!0}return config.routeFiles.includes(candidate)?(log(`Executing route file: ${candidatePath}`,2),await executeRouteModule(candidatePath,req,res,params),!0):(log(`Serving index file: ${candidatePath}`,2),await serveStaticCustomFile(candidatePath,res),!0)}return null}const fileName=path.basename(filePath);if(fileName.endsWith(".page.html")){log(`Rendering page template: ${filePath}`,2);const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,html=await renderPage(filePath,rootPath,globals,state,maxFragmentDepth);return res.writeHead(200,{"Content-Type":"text/html; charset=utf-8"}),res.end(html),!0}return config.routeFiles.includes(fileName)?(log(`Executing route file: ${filePath}`,2),await executeRouteModule(filePath,req,res,params),!0):(await serveStaticCustomFile(filePath,res),!0)},serveCustomRoutePath=async(resolvedFilePath,req,res,customRootDir=null)=>{let fileStat;try{fileStat=await stat(resolvedFilePath);const result=await serveResolvedPath(resolvedFilePath,fileStat,{},req,res);if(result)return result}catch(e){if("ENOENT"!==e.code)throw e}if(!fileStat){let current=resolvedFilePath;const remaining=[];for(;current!==path.dirname(current);){remaining.unshift(path.basename(current)),current=path.dirname(current);try{if(!(await stat(current)).isDirectory())break;const result=await walkDynamic(current,remaining);if(!result)break;const resolvedStat=await stat(result.filePath),served=await serveResolvedPath(result.filePath,resolvedStat,result.params,req,res);if(served)return served;break}catch(e2){if("ENOENT"!==e2.code)throw e2}}}if(config.templating?.ssr&&customRootDir){const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,base=resolvedFilePath.replace(/\.html$/,"").replace(/[\/\\]+$/,"");for(const pageFile of[base+".page.html",path.join(base,"index.page.html")])try{await stat(pageFile);const html=await renderPage(pageFile,customRootDir,globals,state,maxFragmentDepth);return res.writeHead(200,{"Content-Type":"text/html; charset=utf-8"}),res.end(html),log(`SSR rendered custom route: ${pageFile}`,2),!0}catch(e){log(`SSR custom route miss for ${pageFile}: ${e.message}`,3)}}return null},rescanAttempts=new Map,serveCatchFallback=async(requestPath,req,res)=>{const candidates=["CATCH.js","CATCH.html","CATCH.page.html"];let dir=path.join(rootPath,requestPath.startsWith("/")?requestPath.slice(1):requestPath);for(path.extname(dir)&&(dir=path.dirname(dir));dir.startsWith(rootPath);){for(const candidate of candidates){const candidatePath=path.join(dir,candidate);try{await stat(candidatePath)}catch{continue}if(log(`Serving catch fallback: ${candidatePath}`,2),"CATCH.page.html"===candidate){const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,html=await renderPage(candidatePath,rootPath,globals,state,maxFragmentDepth);return res.writeHead(404,{"Content-Type":"text/html; charset=utf-8"}),res.end(html),!0}if("CATCH.js"===candidate)return await executeRouteModule(candidatePath,req,res),!0;const fileContent=await readFile(candidatePath,"utf8");return res.writeHead(404,{"Content-Type":"text/html; charset=utf-8"}),res.end(fileContent),!0}const parent=path.dirname(dir);if(parent===dir)break;dir=parent}return!1},dynamicNoRescanPaths=new Set,shouldSkipRescan=requestPath=>config.noRescanPaths.some(pattern=>new RegExp(pattern).test(requestPath))?(log(`Skipping rescan for configured pattern: ${requestPath}`,3),!0):!!dynamicNoRescanPaths.has(requestPath)&&(log(`Skipping rescan for dynamically blacklisted path: ${requestPath}`,3),!0),handler=async(req,res)=>{if(parseInt(req.headers["content-length"]||"0",10)>config.maxBodySize)return res.writeHead(413,{"Content-Type":"text/plain"}),void res.end("Payload Too Large");const rawBody=await new Promise((resolve,reject)=>{if(["GET","HEAD"].includes(req.method)&&!req.headers["content-length"])return resolve("");let body="",size=0;req.on("data",chunk=>{if(size+=chunk.length,size>config.maxBodySize)return req.destroy(),void reject(new Error("Payload Too Large"));body+=chunk.toString()}),req.on("end",()=>resolve(body)),req.on("error",reject)}).catch(err=>{if("Payload Too Large"===err.message)return res.writeHead(413,{"Content-Type":"text/plain"}),res.end("Payload Too Large"),null;throw err});if(null===rawBody)return;req._bufferedBody=rawBody;const enhancedRequest=createRequestWrapper(req,{}),enhancedResponse=createResponseWrapper(res);enhancedRequest._rawBody=rawBody,enhancedRequest.body=parseBody(rawBody,req.headers["content-type"]),await middlewareRunner.run(enhancedRequest,enhancedResponse,async()=>{const requestPath=enhancedRequest.url.split("?")[0];log(`${enhancedRequest.method} ${requestPath}`,4),log(`customRoutes keys: ${Array.from(customRoutes.keys()).join(", ")}`,4);const normalizePath=p=>{try{let np=decodeURIComponent(p);return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np}catch(e){log(`Warning: Failed to decode URI component "${p}": ${e.message}`,1);let np=p;return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np}},normalizedRequestPath=normalizePath(requestPath);log(`Normalized requestPath: ${normalizedRequestPath}`,4);let matchedKey=null;for(const key of customRoutes.keys())if(normalizePath(key)===normalizedRequestPath){matchedKey=key;break}if(matchedKey){const customFilePath=customRoutes.get(matchedKey);log(`Serving custom route: ${normalizedRequestPath} -> ${customFilePath}`,3);try{if(await serveCustomRoutePath(customFilePath,req,res,customFilePath))return;return log(`Custom route path not found: ${customFilePath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),void res.end("Custom route file not found")}catch(error){return log(`Error serving custom route ${normalizedRequestPath}: ${error.message}`,1),res.writeHead(500,{"Content-Type":"text/plain"}),void res.end("Internal Server Error")}}const wildcardMatch=(requestPath=>{for(const[pattern,filePath]of wildcardRoutes){const matches=matchWildcardRoute(requestPath,pattern);if(matches)return{filePath:filePath,matches:matches}}return null})(requestPath);if(wildcardMatch){const resolvedFilePath=((filePath,matches)=>{let resolvedPath=filePath,matchIndex=1;for(;resolvedPath.includes("**")&&matchIndex<matches.length;)resolvedPath=resolvedPath.replace("**",matches[matchIndex]),matchIndex++;for(;resolvedPath.includes("*")&&matchIndex<matches.length;)resolvedPath=resolvedPath.replace("*",matches[matchIndex]),matchIndex++;return path.isAbsolute(resolvedPath)?resolvedPath:path.resolve(rootPath,resolvedPath)})(wildcardMatch.filePath,wildcardMatch.matches);log(`Serving wildcard route: ${requestPath} -> ${resolvedFilePath}`,3);try{const customRootDir=wildcardMatch.filePath.split("*")[0].replace(/[\/\\]+$/,"");if(await serveCustomRoutePath(resolvedFilePath,req,res,customRootDir))return;log(`Wildcard route path not found: ${requestPath}`,2)}catch(error){return log(`Error serving wildcard route ${requestPath}: ${error.message}`,1),enhancedResponse.writeHead(500,{"Content-Type":"text/plain"}),void enhancedResponse.end("Internal Server Error")}}const served=await serveFile(files,rootPath,requestPath,req.method,config,req,res,log,moduleCache);if(!served&&config.maxRescanAttempts>0&&!shouldSkipRescan(requestPath)){log("File not found, rescanning directory...",1),files=await getFiles(rootPath,config,log),log(`Rescan found ${files.length} files`,2);if(await serveFile(files,rootPath,requestPath,req.method,config,req,res,log,moduleCache))rescanAttempts.delete(requestPath);else{if((requestPath=>{const newAttempts=(rescanAttempts.get(requestPath)||0)+1;rescanAttempts.set(requestPath,newAttempts),newAttempts>config.maxRescanAttempts&&(dynamicNoRescanPaths.add(requestPath),log(`Path ${requestPath} added to dynamic blacklist after ${newAttempts} failed attempts`,1)),log(`Rescan attempt ${newAttempts}/${config.maxRescanAttempts} for: ${requestPath}`,3)})(requestPath),log(`404 - File not found after rescan: ${requestPath}`,1),await serveCatchFallback(requestPath,req,res))return;enhancedResponse.writeHead(404,{"Content-Type":"text/plain"}),enhancedResponse.end("Not Found")}}else if(!served){if(shouldSkipRescan(requestPath)?log(`404 - Skipped rescan for: ${requestPath}`,2):log(`404 - File not found: ${requestPath}`,1),await serveCatchFallback(requestPath,req,res))return;enhancedResponse.writeHead(404,{"Content-Type":"text/plain"}),enhancedResponse.end("Not Found")}})};return handler.moduleCache=moduleCache,handler.getStats=()=>moduleCache?.getStats()||null,handler.logCacheStats=()=>moduleCache?.logStats(log),handler.clearCache=()=>moduleCache?.clear(),handler};

package/dist/serveFile.js

@@ -1 +1 @@
-import path from"path";import{readFile,stat}from"fs/promises";import{pathToFileURL}from"url";import findFile from"./findFile.js";import createRequestWrapper,{readRawBody,parseBody}from"./requestWrapper.js";import createResponseWrapper from"./responseWrapper.js";import{renderPage}from"./templating/index.js";const trySSR=async(rootPath,requestPath,config,res,log)=>{const htmlPath=requestPath.endsWith("/")?requestPath+"index":requestPath,pagePath=path.join(rootPath,htmlPath.replace(/\.html$/,"")+".page.html");try{await stat(pagePath);const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,html=await renderPage(pagePath,rootPath,globals,state,maxFragmentDepth);return res.writeHead(200,{"Content-Type":"text/html; charset=utf-8"}),res.end(html),log(`SSR rendered: ${pagePath}`,2),!0}catch(e){return log(`SSR error for ${requestPath}: ${e.message}`,3),!1}};export default async(files,rootPath,requestPath,method,config,req,res,log,moduleCache=null)=>{if(log(`Attempting to serve: ${requestPath}`,3),config.templating?.ssr&&config.templating?.ssrPriority&&await trySSR(rootPath,requestPath,config,res,log))return!0;const[file,params]=await findFile(files,rootPath,requestPath,method,log);if(!file){if(config.templating?.ssr){if(await trySSR(rootPath,requestPath,config,res,log))return!0;log(`SSR fallback not available for: ${requestPath}`,3)}return log(`No file found for: ${requestPath}`,3),!1}const fileName=path.basename(file);if(log(`Found file: ${file}`,2),config.routeFiles.includes(fileName)){log(`Executing route file: ${fileName}`,2);try{let module;if(moduleCache&&config.cache?.enabled){const fileStats=await stat(file);if(module=moduleCache.get(file,fileStats),module)log(`Using cached module: ${fileName}`,3);else{const fileUrl=pathToFileURL(file).href+`?t=${Date.now()}`;log(`Loading module from: ${fileUrl}`,3),module=await import(fileUrl);const estimatedSizeKB=fileStats.size/1024;moduleCache.set(file,module,fileStats,estimatedSizeKB),log(`Cached module: ${fileName} (${estimatedSizeKB.toFixed(1)}KB)`,3)}}else{const fileUrl=pathToFileURL(file).href+`?t=${Date.now()}`;log(`Loading module from: ${fileUrl}`,3),module=await import(fileUrl)}if("function"==typeof module.default){log(`Executing route function with params: ${JSON.stringify(params)}`,3);const enhancedRequest=createRequestWrapper(req,params),enhancedResponse=createResponseWrapper(res),rawBody=await readRawBody(req);return enhancedRequest._rawBody=rawBody,enhancedRequest.body=parseBody(rawBody,req.headers["content-type"]),moduleCache&&(enhancedRequest._kempoCache=moduleCache),await module.default(enhancedRequest,enhancedResponse),log(`Route executed successfully: ${fileName}`,2),!0}return log(`Route file does not export a function: ${fileName}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Route file does not export a function"),!0}catch(error){return log(`Error loading route file ${fileName}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}else{log(`Serving static file: ${fileName}`,2);try{const fileExtension=path.extname(file).toLowerCase().slice(1),mimeConfig=config.allowedMimes[fileExtension];let mimeType,encoding;"string"==typeof mimeConfig?(mimeType=mimeConfig,encoding=mimeType.startsWith("text/")?"utf8":void 0):(mimeType=mimeConfig?.mime||"application/octet-stream",encoding="utf8"===mimeConfig?.encoding?"utf8":void 0);const fileContent=await readFile(file,encoding);log(`Serving ${file} as ${mimeType} (${fileContent.length} bytes)`,2);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;return res.writeHead(200,{"Content-Type":contentType}),res.end(fileContent),!0}catch(error){return log(`Error reading file ${file}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}};
+import path from"path";import{readFile,stat}from"fs/promises";import{pathToFileURL}from"url";import findFile from"./findFile.js";import createRequestWrapper,{readRawBody,parseBody}from"./requestWrapper.js";import createResponseWrapper from"./responseWrapper.js";import{renderPage}from"./templating/index.js";const trySSR=async(rootPath,requestPath,config,res,log)=>{const htmlPath=requestPath.endsWith("/")?requestPath+"index":requestPath,pagePath=path.join(rootPath,htmlPath.replace(/\.html$/,"")+".page.html");try{await stat(pagePath);const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,html=await renderPage(pagePath,rootPath,globals,state,maxFragmentDepth);return res.writeHead(200,{"Content-Type":"text/html; charset=utf-8"}),res.end(html),log(`SSR rendered: ${pagePath}`,2),!0}catch(e){return log(`SSR error for ${requestPath}: ${e.message}`,3),!1}};export default async(files,rootPath,requestPath,method,config,req,res,log,moduleCache=null)=>{if(log(`Attempting to serve: ${requestPath}`,3),config.templating?.ssr&&config.templating?.ssrPriority&&await trySSR(rootPath,requestPath,config,res,log))return!0;const[file,params]=await findFile(files,rootPath,requestPath,method,log);if(!file){if(config.templating?.ssr){if(await trySSR(rootPath,requestPath,config,res,log))return!0;log(`SSR fallback not available for: ${requestPath}`,3)}return log(`No file found for: ${requestPath}`,3),!1}const fileName=path.basename(file);if(log(`Found file: ${file}`,2),fileName.endsWith(".page.html")){log(`Rendering page template: ${fileName}`,2);try{const{globals:globals,state:state,maxFragmentDepth:maxFragmentDepth}=config.templating,html=await renderPage(file,rootPath,globals,state,maxFragmentDepth);return res.writeHead(200,{"Content-Type":"text/html; charset=utf-8"}),res.end(html),!0}catch(error){return log(`Error rendering page template ${fileName}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}if(config.routeFiles.includes(fileName)){log(`Executing route file: ${fileName}`,2);try{let module;if(moduleCache&&config.cache?.enabled){const fileStats=await stat(file);if(module=moduleCache.get(file,fileStats),module)log(`Using cached module: ${fileName}`,3);else{const fileUrl=pathToFileURL(file).href+`?t=${Date.now()}`;log(`Loading module from: ${fileUrl}`,3),module=await import(fileUrl);const estimatedSizeKB=fileStats.size/1024;moduleCache.set(file,module,fileStats,estimatedSizeKB),log(`Cached module: ${fileName} (${estimatedSizeKB.toFixed(1)}KB)`,3)}}else{const fileUrl=pathToFileURL(file).href+`?t=${Date.now()}`;log(`Loading module from: ${fileUrl}`,3),module=await import(fileUrl)}if("function"==typeof module.default){log(`Executing route function with params: ${JSON.stringify(params)}`,3);const enhancedRequest=createRequestWrapper(req,params),enhancedResponse=createResponseWrapper(res),rawBody=await readRawBody(req);return enhancedRequest._rawBody=rawBody,enhancedRequest.body=parseBody(rawBody,req.headers["content-type"]),moduleCache&&(enhancedRequest._kempoCache=moduleCache),await module.default(enhancedRequest,enhancedResponse),log(`Route executed successfully: ${fileName}`,2),!0}return log(`Route file does not export a function: ${fileName}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Route file does not export a function"),!0}catch(error){return log(`Error loading route file ${fileName}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}else{log(`Serving static file: ${fileName}`,2);try{const fileExtension=path.extname(file).toLowerCase().slice(1),mimeConfig=config.allowedMimes[fileExtension];let mimeType,encoding;"string"==typeof mimeConfig?(mimeType=mimeConfig,encoding=mimeType.startsWith("text/")?"utf8":void 0):(mimeType=mimeConfig?.mime||"application/octet-stream",encoding="utf8"===mimeConfig?.encoding?"utf8":void 0);const fileContent=await readFile(file,encoding);log(`Serving ${file} as ${mimeType} (${fileContent.length} bytes)`,2);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;return res.writeHead(200,{"Content-Type":contentType}),res.end(fileContent),!0}catch(error){return log(`Error reading file ${file}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}};

package/dist/templating/index.js

@@ -1 +1 @@
-import{readFile,writeFile,mkdir,readdir}from"fs/promises";import path from"path";import{extractAttrs,extractContentBlocks,mergeContentBlocks,replaceLocations,resolveVars,resolveIfs,resolveForeach,resolveFragmentTags}from"./parse.js";import{readFileSync,statSync}from"fs";const findFileUpSync=(filename,startDir,rootDir)=>{let dir=startDir;const root=path.resolve(rootDir);for(;;){const candidate=path.join(dir,filename);try{return statSync(candidate),candidate}catch(e){}if(path.resolve(dir)===root)return null;const parent=path.dirname(dir);if(parent===dir)return null;dir=parent}},loadVersion=rootDir=>{try{return JSON.parse(readFileSync(path.join(rootDir,"package.json"),"utf8")).version||""}catch(e){return""}},walkGlobals=async dir=>{const entries=await readdir(dir,{withFileTypes:!0}),results=[];for(const entry of entries){const full=path.join(dir,entry.name);entry.isDirectory()?results.push(...await walkGlobals(full)):entry.name.endsWith(".global.html")&&results.push(full)}return results},loadGlobalContent=async rootDir=>{const files=await walkGlobals(rootDir),maps=await Promise.all(files.map(async f=>extractContentBlocks(await readFile(f,"utf8"))));return mergeContentBlocks(...maps)},renderPage=async(pageFilePath,rootDir,globals={},state={},maxDepth=10,preloadedGlobalContent=null)=>{const pageContent=await readFile(pageFilePath,"utf8"),pageTagMatch=pageContent.match(/^[\s\S]*?<page((?:[^>"']|"[^"]*"|'[^']*')*)>/);if(!pageTagMatch)throw new Error(`Invalid page file: missing <page> root element in ${pageFilePath}`);const pageAttrs=extractAttrs(pageTagMatch[1]),templateName=pageAttrs.template||"default";delete pageAttrs.template;const pageDir=path.dirname(pageFilePath),templateFile=findFileUpSync(`${templateName}.template.html`,pageDir,rootDir);if(!templateFile)throw new Error(`Template not found: ${templateName}.template.html (searched from ${pageDir} to ${rootDir})`);const globalContent=preloadedGlobalContent??await loadGlobalContent(rootDir),rawPageBlocks=extractContentBlocks(pageContent),pageBlocks={};for(const[name,entries]of Object.entries(rawPageBlocks))pageBlocks[name]=entries.map(e=>({...e,html:replaceLocations(e.html,globalContent)}));const contentBlocks=mergeContentBlocks(pageBlocks,globalContent);let templateHtml=readFileSync(templateFile,"utf8");templateHtml=resolveFragmentTags(templateHtml,name=>{const filePath=findFileUpSync(name+".fragment.html",pageDir,rootDir);return filePath?readFileSync(filePath,"utf8"):null},0,maxDepth),templateHtml=replaceLocations(templateHtml,contentBlocks);const rel=path.relative(rootDir,path.dirname(pageFilePath)),depth=rel?rel.split(path.sep).length:0,now=new Date,vars={pathToRoot:depth>0?"../".repeat(depth):"./",year:String(now.getFullYear()),date:now.toISOString().slice(0,10),datetime:now.toISOString(),timestamp:String(Date.now()),version:loadVersion(rootDir),env:process.env.NODE_ENV||"",...globals,...state,...pageAttrs};for(const[key,val]of Object.entries(vars))"function"==typeof val&&(vars[key]=val());return templateHtml=resolveIfs(templateHtml,vars),templateHtml=resolveForeach(templateHtml,vars),templateHtml=resolveVars(templateHtml,vars),templateHtml},walkPages=async dir=>{const entries=await readdir(dir,{withFileTypes:!0}),results=[];for(const entry of entries){const full=path.join(dir,entry.name);entry.isDirectory()?results.push(...await walkPages(full)):entry.name.endsWith(".page.html")&&results.push(full)}return results},renderDir=async(inputDir,outputDir,globals={},state={},maxDepth=10)=>{const[pages,globalContent]=await Promise.all([walkPages(inputDir),loadGlobalContent(inputDir)]);let count=0;for(const page of pages){const outRel=path.relative(inputDir,page).replace(/\.page\.html$/,".html"),outPath=path.join(outputDir,outRel);await mkdir(path.dirname(outPath),{recursive:!0});const html=await renderPage(page,inputDir,globals,state,maxDepth,globalContent);await writeFile(outPath,html,"utf8"),count++}return count};export{renderPage,renderDir};
+import{readFile,writeFile,mkdir,readdir}from"fs/promises";import path from"path";import{extractAttrs,extractContentBlocks,mergeContentBlocks,replaceLocations,resolveVars,resolveIfs,resolveForeach,resolveFragmentTags}from"./parse.js";import{readFileSync,statSync}from"fs";const findFileUpSync=(filename,startDir,rootDir)=>{let dir=startDir;const root=path.resolve(rootDir);for(;;){const candidate=path.join(dir,filename);try{return statSync(candidate),candidate}catch(e){}if(path.resolve(dir)===root)return null;const parent=path.dirname(dir);if(parent===dir)return null;dir=parent}},loadVersion=rootDir=>{try{return JSON.parse(readFileSync(path.join(rootDir,"package.json"),"utf8")).version||""}catch(e){return""}},walkGlobals=async dir=>{const entries=await readdir(dir,{withFileTypes:!0}),results=[];for(const entry of entries){const full=path.join(dir,entry.name);entry.isDirectory()?results.push(...await walkGlobals(full)):entry.name.endsWith(".global.html")&&results.push(full)}return results},loadGlobalContent=async rootDir=>{const files=await walkGlobals(rootDir),maps=await Promise.all(files.map(async f=>extractContentBlocks(await readFile(f,"utf8"))));return mergeContentBlocks(...maps)},renderPage=async(pageFilePath,rootDir,globals={},state={},maxDepth=10,preloadedGlobalContent=null)=>{const pageContent=await readFile(pageFilePath,"utf8"),pageTagMatch=pageContent.match(/^[\s\S]*?<page((?:[^>"']|"[^"]*"|'[^']*')*)>/);if(!pageTagMatch)throw new Error(`Invalid page file: missing <page> root element in ${pageFilePath}`);const pageAttrs=extractAttrs(pageTagMatch[1]),templateName=pageAttrs.template||"default";delete pageAttrs.template;const pageDir=path.dirname(pageFilePath);let templateFile=findFileUpSync(`${templateName}.template.html`,pageDir,rootDir);if(templateFile||"default"===templateName||(templateFile=findFileUpSync("default.template.html",pageDir,rootDir)),!templateFile)throw new Error(`Template not found: ${templateName}.template.html or default.template.html (searched from ${pageDir} to ${rootDir})`);const globalContent=preloadedGlobalContent??await loadGlobalContent(rootDir),rawPageBlocks=extractContentBlocks(pageContent),pageBlocks={};for(const[name,entries]of Object.entries(rawPageBlocks))pageBlocks[name]=entries.map(e=>({...e,html:replaceLocations(e.html,globalContent)}));const contentBlocks=mergeContentBlocks(pageBlocks,globalContent);let templateHtml=readFileSync(templateFile,"utf8");templateHtml=resolveFragmentTags(templateHtml,name=>{const filePath=findFileUpSync(name+".fragment.html",pageDir,rootDir);return filePath?readFileSync(filePath,"utf8"):null},0,maxDepth),templateHtml=replaceLocations(templateHtml,contentBlocks);const rel=path.relative(rootDir,path.dirname(pageFilePath)),depth=rel?rel.split(path.sep).length:0,now=new Date,vars={pathToRoot:depth>0?"../".repeat(depth):"./",year:String(now.getFullYear()),date:now.toISOString().slice(0,10),datetime:now.toISOString(),timestamp:String(Date.now()),version:loadVersion(rootDir),env:process.env.NODE_ENV||"",...globals,...state,...pageAttrs};for(const[key,val]of Object.entries(vars))"function"==typeof val&&(vars[key]=val());return templateHtml=resolveIfs(templateHtml,vars),templateHtml=resolveForeach(templateHtml,vars),templateHtml=resolveVars(templateHtml,vars),templateHtml},walkPages=async dir=>{const entries=await readdir(dir,{withFileTypes:!0}),results=[];for(const entry of entries){const full=path.join(dir,entry.name);entry.isDirectory()?results.push(...await walkPages(full)):entry.name.endsWith(".page.html")&&results.push(full)}return results},renderDir=async(inputDir,outputDir,globals={},state={},maxDepth=10)=>{const[pages,globalContent]=await Promise.all([walkPages(inputDir),loadGlobalContent(inputDir)]);let count=0;for(const page of pages){const outRel=path.relative(inputDir,page).replace(/\.page\.html$/,".html"),outPath=path.join(outputDir,outRel);await mkdir(path.dirname(outPath),{recursive:!0});const html=await renderPage(page,inputDir,globals,state,maxDepth,globalContent);await writeFile(outPath,html,"utf8"),count++}return count};export{renderPage,renderDir};

package/docs/routing.html

@@ -114,10 +114,15 @@
     <h2 id="htmlRoutes">HTML Routes</h2>
     <p>Just like JS files, HTML files can be used to define a route. Use <code>GET.html</code>, <code>POST.html</code>, etc... to define files that will be served when that route is requested.</p>
     <pre><code class="hljs markdown">my/<br />├─ route/<br />│  ├─ GET.js<br />│  ├─ POST.js<br />├─ other/<br />│  ├─ route/<br />│  │  ├─ GET.js<br />│  ├─ POST.html<br />│  ├─ GET.html<br /></code></pre>
+
+    <h2 id="pageHtmlRoutes">Template Page Routes</h2>
+    <p>You can use <code>.page.html</code> files as route handlers. These files are rendered through the <a href="templating.html">templating system</a>, so they support templates, fragments, globals, and all other templating features. Use <code>GET.page.html</code>, <code>POST.page.html</code>, etc... to define template-rendered routes for specific methods, or <code>index.page.html</code> as a fallback for all methods.</p>
+    <pre><code class="hljs markdown">my/<br />├─ route/<br />│  ├─ GET.js<br />│  ├─ POST.page.html<br />├─ other/<br />│  ├─ GET.page.html<br />│  ├─ index.page.html<br /></code></pre>
+    <p><code>.page.html</code> routes are a lower priority than their <code>.js</code> and <code>.html</code> counterparts. If both <code>GET.js</code> and <code>GET.page.html</code> exist in the same directory, <code>GET.js</code> will be used.</p>
     
     <h3><code>index</code> fallbacks</h3>
-    <p><code>index.js</code> or <code>index.html</code> will be used as a fallback for all routes if a <i>method</i> file is not defined. In the above examples we do not have any routes defined for <code>DELETE</code>, <code>PUT</code> <code>PATCH</code>, etc... so lets use an <code>index.js</code> and <code>index.html</code> to be a "catch-all" for all the methods we have not created handlers for.</p>
-    <pre><code class="hljs markdown">my/<br />├─ route/<br />│  ├─ GET.js<br />│  ├─ POST.js<br />│  ├─ index.js<br />├─ other/<br />│  ├─ route/<br />│  │  ├─ GET.js<br />│  │  ├─ index.js<br />│  ├─ POST.html<br />│  ├─ GET.html<br />│  ├─ index.html<br />├─ index.html<br /></code></pre>
+    <p><code>index.js</code>, <code>index.html</code>, or <code>index.page.html</code> will be used as a fallback for all routes if a <i>method</i> file is not defined. In the above examples we do not have any routes defined for <code>DELETE</code>, <code>PUT</code> <code>PATCH</code>, etc... so lets use an <code>index.js</code>, <code>index.html</code>, and <code>index.page.html</code> to be a "catch-all" for all the methods we have not created handlers for.</p>
+    <pre><code class="hljs markdown">my/<br />├─ route/<br />│  ├─ GET.js<br />│  ├─ POST.js<br />│  ├─ index.js<br />├─ other/<br />│  ├─ route/<br />│  │  ├─ GET.js<br />│  │  ├─ index.js<br />│  ├─ POST.html<br />│  ├─ GET.html<br />│  ├─ index.html<br />├─ index.page.html<br /></code></pre>
 
     <h2>Dynamic Routes</h2>
     <p>A dynamic route is a route with a "param" in its path. To define the dynamic parts of the route just wrap the directory name in square brackets. For example if you wanted to get a users profile, or perform CRUD operations on a user you might create the following directory structure.</p>
@@ -160,13 +165,41 @@
     <p>Example static file structure:</p>
     <pre><code class="hljs markdown">public/<br />├─ index.html         # Served at /<br />├─ styles.css         # Served at /styles.css<br />├─ script.js          # Served at /script.js<br />├─ images/<br />│  ├─ logo.png        # Served at /images/logo.png<br />├─ api/               # Routes directory<br />│  ├─ hello/GET.js    # Route handler<br /></code></pre>
 
+    <h2 id="catchHandler">Catch Fallback Handler</h2>
+    <p>A <code>CATCH</code> file is a special handler that catches requests to any undefined deeper paths within that directory. When a request doesn't match any route or static file, the server walks up the directory tree from the requested path looking for the closest <code>CATCH</code> handler.</p>
+    <p>Unlike <code>index</code> files which handle a specific directory, <code>CATCH</code> files are fallbacks for undefined paths below that directory. This makes them perfect for handling REST-style path parameters or serving custom error pages.</p>
+    <p>The server checks each directory for the following files in priority order:</p>
+    <ol>
+      <li><code>CATCH.js</code> &mdash; executed as a route module (you control the full response, status code, format)</li>
+      <li><code>CATCH.html</code> &mdash; served as static HTML with a 404 status code</li>
+      <li><code>CATCH.page.html</code> &mdash; rendered through the <a href="templating.html">templating system</a> with a 404 status code</li>
+    </ol>
+    <p>If no <code>CATCH</code> handler is found in the current directory, the server moves up one directory and checks again, repeating until it reaches the server root. This means you can define a root-level <code>CATCH.page.html</code> as a global fallback and override it with more specific handlers in subdirectories.</p>
+    <pre><code class="hljs markdown">public/<br />├─ CATCH.page.html          # Global fallback for all paths<br />├─ index.html<br />├─ docs/<br />│  ├─ CATCH.page.html       # Docs-specific fallback<br />│  ├─ index.html<br />├─ api/<br />│  ├─ CATCH.js              # API-specific handler (can return JSON, custom status, etc.)<br />│  ├─ users/<br />│  │  ├─ GET.js<br /></code></pre>
+    <p>With this structure:</p>
+    <ul>
+      <li>A request to <code>/api/users/123/profile</code> (where <code>profile</code> doesn't exist) would use <code>api/CATCH.js</code></li>
+      <li>A request to <code>/docs/nonexistent/path</code> would use <code>docs/CATCH.page.html</code></li>
+      <li>A request to <code>/other/deep/undefined/path</code> would walk up to <code>CATCH.page.html</code> at the root</li>
+    </ul>
+    <p>If no <code>CATCH</code> handler is found anywhere in the tree, the server responds with a plain text "Not Found" response.</p>
+    
+    <h3>Using CATCH for Dynamic Route Parameters</h3>
+    <p>A common use case is using <code>CATCH.js</code> to handle REST-style path parameters. For example, an <code>api/CATCH.js</code> handler can parse path segments and respond with data or status codes as appropriate:</p>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// api/CATCH.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> path = request.url.split(<span class="hljs-string">'?'</span>)[<span class="hljs-number">0</span>];<br />  <span class="hljs-keyword">const</span> parts = path.replace(<span class="hljs-string">/\\/api\\//</span>, <span class="hljs-string">''</span>).split(<span class="hljs-string">'/'</span>).filter(Boolean);<br />  <br />  <span class="hljs-comment">// Parse alternating keys and values: /key1/value1/key2/value2</span><br />  <span class="hljs-keyword">const</span> params = {};<br />  <span class="hljs-keyword">for</span> (<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>; i &lt; parts.length; i += <span class="hljs-number">2</span>) {<br />    params[parts[i]] = parts[i + <span class="hljs-number">1</span>];<br />  }<br />  <br />  <span class="hljs-keyword">if</span> (Object.keys(params).length === <span class="hljs-number">0</span>) {<br />    response.status(<span class="hljs-number">404</span>).json({error: <span class="hljs-string\">'No parameters provided'</span>});<br />  } <span class="hljs-keyword\">else</span> {<br />    response.json({params, message: <span class="hljs-string\">'Caught by CATCH handler'</span>});<br />  }<br />}</code></pre>
+
     <h2>Custom Route Directory Resolution</h2>
     <p>When using <code>customRoutes</code> (see <a href="configuration.html#customRoutes">Configuration</a>), routes that resolve to a directory support full file-based routing. The server checks for route files and index files inside the directory using the same priority order as normal routing:</p>
     <ol>
       <li><code>METHOD.js</code> (e.g. <code>GET.js</code>, <code>POST.js</code>) &mdash; executed as a route module</li>
       <li><code>METHOD.html</code> (e.g. <code>GET.html</code>) &mdash; served as static</li>
+      <li><code>METHOD.page.html</code> (e.g. <code>GET.page.html</code>) &mdash; rendered via templating</li>
       <li><code>index.js</code> &mdash; executed as a route module</li>
       <li><code>index.html</code> / <code>index.htm</code> &mdash; served as static</li>
+      <li><code>index.page.html</code> &mdash; rendered via templating</li>
+      <li><code>CATCH.js</code> &mdash; fallback handler for undefined deeper paths</li>
+      <li><code>CATCH.html</code> &mdash; fallback served as static</li>
+      <li><code>CATCH.page.html</code> &mdash; fallback rendered via templating</li>
     </ol>
     <p>This applies to both exact and wildcard custom routes. For example, with a wildcard route <code>"/api/**": "../api/**"</code>, a request to <code>/api/auth/session</code> resolves to the <code>../api/auth/session/</code> directory and executes the appropriate route file (e.g. <code>GET.js</code> for GET requests).</p>
 	

package/docs-src/routing.page.html

@@ -14,10 +14,15 @@
     <h2 id="htmlRoutes">HTML Routes</h2>
     <p>Just like JS files, HTML files can be used to define a route. Use <code>GET.html</code>, <code>POST.html</code>, etc... to define files that will be served when that route is requested.</p>
     <pre><code class="hljs markdown">my/<br />├─ route/<br />│  ├─ GET.js<br />│  ├─ POST.js<br />├─ other/<br />│  ├─ route/<br />│  │  ├─ GET.js<br />│  ├─ POST.html<br />│  ├─ GET.html<br /></code></pre>
+
+    <h2 id="pageHtmlRoutes">Template Page Routes</h2>
+    <p>You can use <code>.page.html</code> files as route handlers. These files are rendered through the <a href="templating.html">templating system</a>, so they support templates, fragments, globals, and all other templating features. Use <code>GET.page.html</code>, <code>POST.page.html</code>, etc... to define template-rendered routes for specific methods, or <code>index.page.html</code> as a fallback for all methods.</p>
+    <pre><code class="hljs markdown">my/<br />├─ route/<br />│  ├─ GET.js<br />│  ├─ POST.page.html<br />├─ other/<br />│  ├─ GET.page.html<br />│  ├─ index.page.html<br /></code></pre>
+    <p><code>.page.html</code> routes are a lower priority than their <code>.js</code> and <code>.html</code> counterparts. If both <code>GET.js</code> and <code>GET.page.html</code> exist in the same directory, <code>GET.js</code> will be used.</p>
     
     <h3><code>index</code> fallbacks</h3>
-    <p><code>index.js</code> or <code>index.html</code> will be used as a fallback for all routes if a <i>method</i> file is not defined. In the above examples we do not have any routes defined for <code>DELETE</code>, <code>PUT</code> <code>PATCH</code>, etc... so lets use an <code>index.js</code> and <code>index.html</code> to be a "catch-all" for all the methods we have not created handlers for.</p>
-    <pre><code class="hljs markdown">my/<br />├─ route/<br />│  ├─ GET.js<br />│  ├─ POST.js<br />│  ├─ index.js<br />├─ other/<br />│  ├─ route/<br />│  │  ├─ GET.js<br />│  │  ├─ index.js<br />│  ├─ POST.html<br />│  ├─ GET.html<br />│  ├─ index.html<br />├─ index.html<br /></code></pre>
+    <p><code>index.js</code>, <code>index.html</code>, or <code>index.page.html</code> will be used as a fallback for all routes if a <i>method</i> file is not defined. In the above examples we do not have any routes defined for <code>DELETE</code>, <code>PUT</code> <code>PATCH</code>, etc... so lets use an <code>index.js</code>, <code>index.html</code>, and <code>index.page.html</code> to be a "catch-all" for all the methods we have not created handlers for.</p>
+    <pre><code class="hljs markdown">my/<br />├─ route/<br />│  ├─ GET.js<br />│  ├─ POST.js<br />│  ├─ index.js<br />├─ other/<br />│  ├─ route/<br />│  │  ├─ GET.js<br />│  │  ├─ index.js<br />│  ├─ POST.html<br />│  ├─ GET.html<br />│  ├─ index.html<br />├─ index.page.html<br /></code></pre>
 
     <h2>Dynamic Routes</h2>
     <p>A dynamic route is a route with a "param" in its path. To define the dynamic parts of the route just wrap the directory name in square brackets. For example if you wanted to get a users profile, or perform CRUD operations on a user you might create the following directory structure.</p>
@@ -60,13 +65,41 @@
     <p>Example static file structure:</p>
     <pre><code class="hljs markdown">public/<br />├─ index.html         # Served at /<br />├─ styles.css         # Served at /styles.css<br />├─ script.js          # Served at /script.js<br />├─ images/<br />│  ├─ logo.png        # Served at /images/logo.png<br />├─ api/               # Routes directory<br />│  ├─ hello/GET.js    # Route handler<br /></code></pre>
 
+    <h2 id="catchHandler">Catch Fallback Handler</h2>
+    <p>A <code>CATCH</code> file is a special handler that catches requests to any undefined deeper paths within that directory. When a request doesn't match any route or static file, the server walks up the directory tree from the requested path looking for the closest <code>CATCH</code> handler.</p>
+    <p>Unlike <code>index</code> files which handle a specific directory, <code>CATCH</code> files are fallbacks for undefined paths below that directory. This makes them perfect for handling REST-style path parameters or serving custom error pages.</p>
+    <p>The server checks each directory for the following files in priority order:</p>
+    <ol>
+      <li><code>CATCH.js</code> &mdash; executed as a route module (you control the full response, status code, format)</li>
+      <li><code>CATCH.html</code> &mdash; served as static HTML with a 404 status code</li>
+      <li><code>CATCH.page.html</code> &mdash; rendered through the <a href="templating.html">templating system</a> with a 404 status code</li>
+    </ol>
+    <p>If no <code>CATCH</code> handler is found in the current directory, the server moves up one directory and checks again, repeating until it reaches the server root. This means you can define a root-level <code>CATCH.page.html</code> as a global fallback and override it with more specific handlers in subdirectories.</p>
+    <pre><code class="hljs markdown">public/<br />├─ CATCH.page.html          # Global fallback for all paths<br />├─ index.html<br />├─ docs/<br />│  ├─ CATCH.page.html       # Docs-specific fallback<br />│  ├─ index.html<br />├─ api/<br />│  ├─ CATCH.js              # API-specific handler (can return JSON, custom status, etc.)<br />│  ├─ users/<br />│  │  ├─ GET.js<br /></code></pre>
+    <p>With this structure:</p>
+    <ul>
+      <li>A request to <code>/api/users/123/profile</code> (where <code>profile</code> doesn't exist) would use <code>api/CATCH.js</code></li>
+      <li>A request to <code>/docs/nonexistent/path</code> would use <code>docs/CATCH.page.html</code></li>
+      <li>A request to <code>/other/deep/undefined/path</code> would walk up to <code>CATCH.page.html</code> at the root</li>
+    </ul>
+    <p>If no <code>CATCH</code> handler is found anywhere in the tree, the server responds with a plain text "Not Found" response.</p>
+    
+    <h3>Using CATCH for Dynamic Route Parameters</h3>
+    <p>A common use case is using <code>CATCH.js</code> to handle REST-style path parameters. For example, an <code>api/CATCH.js</code> handler can parse path segments and respond with data or status codes as appropriate:</p>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// api/CATCH.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> path = request.url.split(<span class="hljs-string">'?'</span>)[<span class="hljs-number">0</span>];<br />  <span class="hljs-keyword">const</span> parts = path.replace(<span class="hljs-string">/\\/api\\//</span>, <span class="hljs-string">''</span>).split(<span class="hljs-string">'/'</span>).filter(Boolean);<br />  <br />  <span class="hljs-comment">// Parse alternating keys and values: /key1/value1/key2/value2</span><br />  <span class="hljs-keyword">const</span> params = {};<br />  <span class="hljs-keyword">for</span> (<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>; i &lt; parts.length; i += <span class="hljs-number">2</span>) {<br />    params[parts[i]] = parts[i + <span class="hljs-number">1</span>];<br />  }<br />  <br />  <span class="hljs-keyword">if</span> (Object.keys(params).length === <span class="hljs-number">0</span>) {<br />    response.status(<span class="hljs-number">404</span>).json({error: <span class="hljs-string\">'No parameters provided'</span>});<br />  } <span class="hljs-keyword\">else</span> {<br />    response.json({params, message: <span class="hljs-string\">'Caught by CATCH handler'</span>});<br />  }<br />}</code></pre>
+
     <h2>Custom Route Directory Resolution</h2>
     <p>When using <code>customRoutes</code> (see <a href="configuration.html#customRoutes">Configuration</a>), routes that resolve to a directory support full file-based routing. The server checks for route files and index files inside the directory using the same priority order as normal routing:</p>
     <ol>
       <li><code>METHOD.js</code> (e.g. <code>GET.js</code>, <code>POST.js</code>) &mdash; executed as a route module</li>
       <li><code>METHOD.html</code> (e.g. <code>GET.html</code>) &mdash; served as static</li>
+      <li><code>METHOD.page.html</code> (e.g. <code>GET.page.html</code>) &mdash; rendered via templating</li>
       <li><code>index.js</code> &mdash; executed as a route module</li>
       <li><code>index.html</code> / <code>index.htm</code> &mdash; served as static</li>
+      <li><code>index.page.html</code> &mdash; rendered via templating</li>
+      <li><code>CATCH.js</code> &mdash; fallback handler for undefined deeper paths</li>
+      <li><code>CATCH.html</code> &mdash; fallback served as static</li>
+      <li><code>CATCH.page.html</code> &mdash; fallback rendered via templating</li>
     </ol>
     <p>This applies to both exact and wildcard custom routes. For example, with a wildcard route <code>"/api/**": "../api/**"</code>, a request to <code>/api/auth/session</code> resolves to the <code>../api/auth/session/</code> directory and executes the appropriate route file (e.g. <code>GET.js</code> for GET requests).</p>
 	</content>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kempo-server",
   "type": "module",
-  "version": "3.0.7",
+  "version": "3.0.9",
   "description": "A lightweight, zero-dependency, file based routing server.",
   "exports": {
     "./rescan": "./dist/rescan.js",

package/src/defaultConfig.js

@@ -62,8 +62,7 @@ export default {
     "package\\.json$",
     "package-lock\\.json$",
     "\\.template\\.html$",
-    "\\.fragment\\.html$",
-    "\\.page\\.html$"
+    "\\.fragment\\.html$"
   ],
   routeFiles: [
     'GET.js',
@@ -75,7 +74,19 @@ export default {
     'PATCH.js',
     'CONNECT.js',
     'TRACE.js',
-    'index.js'
+    'index.js',
+    'GET.page.html',
+    'POST.page.html',
+    'PUT.page.html',
+    'DELETE.page.html',
+    'HEAD.page.html',
+    'OPTIONS.page.html',
+    'PATCH.page.html',
+    'CONNECT.page.html',
+    'TRACE.page.html',
+    'index.page.html',
+    'CATCH.js',
+    'CATCH.page.html'
   ],
   noRescanPaths: [
     "^/\\.well-known/",

package/src/findFile.js

@@ -45,12 +45,17 @@ export default (files, rootPath, requestPath, method, log) => {
     const dirPath = normalizeRequestPath || '';
     const methodUpper = method.toUpperCase();
     
-    // Priority order: METHOD.js, METHOD.html, index.js, index.html
+    // Priority order: METHOD.js, METHOD.html, METHOD.page.html, index.js, index.html, index.page.html
     const indexFiles = [
       `${methodUpper}.js`,
       `${methodUpper}.html`,
+      `${methodUpper}.page.html`,
       'index.js',
-      'index.html'
+      'index.html',
+      'index.page.html',
+      'CATCH.js',
+      'CATCH.html',
+      'CATCH.page.html'
     ];
     
     log(`Looking for index files: [${indexFiles.join(', ')}]`, 3);
@@ -116,8 +121,13 @@ export default (files, rootPath, requestPath, method, log) => {
         const indexFiles = [
           `${methodUpper}.js`,
           `${methodUpper}.html`,
+          `${methodUpper}.page.html`,
           'index.js',
-          'index.html'
+          'index.html',
+          'index.page.html',
+          'CATCH.js',
+          'CATCH.html',
+          'CATCH.page.html'
         ];
         
         const priority = indexFiles.indexOf(fileName);

package/src/router.js

@@ -403,13 +403,26 @@ export default async (flags, log) => {
       const candidates = [
         `${methodUpper}.js`,
         `${methodUpper}.html`,
+        `${methodUpper}.page.html`,
         'index.js',
         'index.html',
-        'index.htm'
+        'index.page.html',
+        'index.htm',
+        'CATCH.js',
+        'CATCH.html',
+        'CATCH.page.html'
       ];
       for(const candidate of candidates) {
         const candidatePath = path.join(filePath, candidate);
         try { await stat(candidatePath); } catch { continue; }
+        if(candidate.endsWith('.page.html')) {
+          log(`Rendering page template: ${candidatePath}`, 2);
+          const {globals, state, maxFragmentDepth} = config.templating;
+          const html = await renderPage(candidatePath, rootPath, globals, state, maxFragmentDepth);
+          res.writeHead(200, {'Content-Type': 'text/html; charset=utf-8'});
+          res.end(html);
+          return true;
+        }
         if(config.routeFiles.includes(candidate)) {
           log(`Executing route file: ${candidatePath}`, 2);
           await executeRouteModule(candidatePath, req, res, params);
@@ -423,6 +436,14 @@ export default async (flags, log) => {
     }
 
     const fileName = path.basename(filePath);
+    if(fileName.endsWith('.page.html')) {
+      log(`Rendering page template: ${filePath}`, 2);
+      const {globals, state, maxFragmentDepth} = config.templating;
+      const html = await renderPage(filePath, rootPath, globals, state, maxFragmentDepth);
+      res.writeHead(200, {'Content-Type': 'text/html; charset=utf-8'});
+      res.end(html);
+      return true;
+    }
     if(config.routeFiles.includes(fileName)) {
       log(`Executing route file: ${filePath}`, 2);
       await executeRouteModule(filePath, req, res, params);
@@ -491,6 +512,43 @@ export default async (flags, log) => {
 
   // Track 404 attempts to avoid unnecessary rescans
   const rescanAttempts = new Map(); // path -> attempt count
+
+  // Walk up the directory tree from requestPath looking for CATCH.js, CATCH.html, CATCH.page.html.
+  // Returns true if a catch fallback handler was found and served, false otherwise.
+  const serveCatchFallback = async (requestPath, req, res) => {
+    const candidates = ['CATCH.js', 'CATCH.html', 'CATCH.page.html'];
+    let dir = path.join(rootPath, requestPath.startsWith('/') ? requestPath.slice(1) : requestPath);
+    // Start from the requested directory (or its parent if it's a file path)
+    if(path.extname(dir)) dir = path.dirname(dir);
+
+    while(dir.startsWith(rootPath)) {
+      for(const candidate of candidates) {
+        const candidatePath = path.join(dir, candidate);
+        try { await stat(candidatePath); } catch { continue; }
+        log(`Serving catch fallback: ${candidatePath}`, 2);
+        if(candidate === 'CATCH.page.html') {
+          const {globals, state, maxFragmentDepth} = config.templating;
+          const html = await renderPage(candidatePath, rootPath, globals, state, maxFragmentDepth);
+          res.writeHead(404, {'Content-Type': 'text/html; charset=utf-8'});
+          res.end(html);
+          return true;
+        }
+        if(candidate === 'CATCH.js') {
+          await executeRouteModule(candidatePath, req, res);
+          return true;
+        }
+        // CATCH.html — serve static with 404 status
+        const fileContent = await readFile(candidatePath, 'utf8');
+        res.writeHead(404, {'Content-Type': 'text/html; charset=utf-8'});
+        res.end(fileContent);
+        return true;
+      }
+      const parent = path.dirname(dir);
+      if(parent === dir) break;
+      dir = parent;
+    }
+    return false;
+  };
   const dynamicNoRescanPaths = new Set(); // paths that have exceeded max attempts
   
   // Helper function to check if a path should skip rescanning
@@ -657,6 +715,7 @@ export default async (flags, log) => {
         if (!reserved) {
           trackRescanAttempt(requestPath);
           log(`404 - File not found after rescan: ${requestPath}`, 1);
+          if(await serveCatchFallback(requestPath, req, res)) return;
           enhancedResponse.writeHead(404, { 'Content-Type': 'text/plain' });
           enhancedResponse.end('Not Found');
         } else {
@@ -669,6 +728,7 @@ export default async (flags, log) => {
         } else {
           log(`404 - File not found: ${requestPath}`, 1);
         }
+        if(await serveCatchFallback(requestPath, req, res)) return;
         enhancedResponse.writeHead(404, { 'Content-Type': 'text/plain' });
         enhancedResponse.end('Not Found');
       }

package/src/serveFile.js

@@ -44,6 +44,22 @@ export default async (files, rootPath, requestPath, method, config, req, res, lo
   const fileName = path.basename(file);
   log(`Found file: ${file}`, 2);
   
+  if(fileName.endsWith('.page.html')) {
+    log(`Rendering page template: ${fileName}`, 2);
+    try {
+      const {globals, state, maxFragmentDepth} = config.templating;
+      const html = await renderPage(file, rootPath, globals, state, maxFragmentDepth);
+      res.writeHead(200, {'Content-Type': 'text/html; charset=utf-8'});
+      res.end(html);
+      return true;
+    } catch(error) {
+      log(`Error rendering page template ${fileName}: ${error.message}`, 0);
+      res.writeHead(500, {'Content-Type': 'text/plain'});
+      res.end('Internal Server Error');
+      return true;
+    }
+  }
+
   // Check if this is a route file that should be executed as a module
   if (config.routeFiles.includes(fileName)) {
     log(`Executing route file: ${fileName}`, 2);

package/src/templating/index.js

@@ -74,8 +74,14 @@ const renderPage = async (pageFilePath, rootDir, globals = {}, state = {}, maxDe
   delete pageAttrs.template;
 
   const pageDir = path.dirname(pageFilePath);
-  const templateFile = findFileUpSync(`${templateName}.template.html`, pageDir, rootDir);
-  if(!templateFile) throw new Error(`Template not found: ${templateName}.template.html (searched from ${pageDir} to ${rootDir})`);
+  let templateFile = findFileUpSync(`${templateName}.template.html`, pageDir, rootDir);
+
+  // If the specified template is not found, fall back to default.template.html
+  if (!templateFile && templateName !== 'default') {
+    templateFile = findFileUpSync('default.template.html', pageDir, rootDir);
+  }
+
+  if(!templateFile) throw new Error(`Template not found: ${templateName}.template.html or default.template.html (searched from ${pageDir} to ${rootDir})`);
 
   const globalContent = preloadedGlobalContent ?? await loadGlobalContent(rootDir);
   const rawPageBlocks = extractContentBlocks(pageContent);

package/tests/router-catch-fallback.node-test.js

@@ -0,0 +1,275 @@
+import http from 'http';
+import path from 'path';
+import {withTempDir} from './utils/temp-dir.js';
+import {write} from './utils/file-writer.js';
+import {randomPort} from './utils/port.js';
+import {httpGet} from './utils/http.js';
+import router from '../src/router.js';
+
+const template = '<html><body><location name="main" /></body></html>';
+const noop = () => {};
+
+const startServer = async (dir, flags, config = {}) => {
+  await write(dir, `${flags.root}/.config.json`, JSON.stringify(config));
+  const handler = await router({...flags, logging: 0}, noop);
+  const server = http.createServer(handler);
+  const port = randomPort();
+  await new Promise(r => server.listen(port, r));
+  await new Promise(r => setTimeout(r, 30));
+  return {server, port};
+};
+
+export default {
+  'CATCH.html in same directory serves with 404 status': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+        await write(dir, 'public/CATCH.html', '<h1>Not Found</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/nonexistent`);
+          if(r.res.statusCode !== 404) throw new Error(`expected 404, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          if(!body.includes('<h1>Not Found</h1>')) throw new Error(`missing content: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'CATCH.page.html renders through templating with 404 status': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        const page = '<page template="default"><content location="main"><h1>Custom Catch</h1></content></page>';
+        await write(dir, 'public/default.template.html', template);
+        await write(dir, 'public/CATCH.page.html', page);
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/nonexistent`);
+          if(r.res.statusCode !== 404) throw new Error(`expected 404, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          if(!body.includes('<h1>Custom Catch</h1>')) throw new Error(`missing page content: ${body}`);
+          if(!body.includes('<html>')) throw new Error(`missing template wrapper: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'CATCH.js executes as route module': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        const handler = 'export default async (req, res) => { res.writeHead(404, {"Content-Type":"application/json"}); res.end(JSON.stringify({error: "catch handler", path: req.url})); };';
+        await write(dir, 'public/CATCH.js', handler);
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/nonexistent`);
+          const body = r.body.toString();
+          const json = JSON.parse(body);
+          if(json.error !== 'catch handler') throw new Error(`unexpected response: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'CATCH fallback walks up directory tree to find closest handler': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+        await write(dir, 'public/CATCH.html', '<h1>Root Catch</h1>');
+        await write(dir, 'public/deep/CATCH.html', '<h1>Deep Catch</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          // Request under /deep/ should find deep/CATCH.html
+          const r1 = await httpGet(`http://localhost:${port}/deep/nonexistent`);
+          if(r1.res.statusCode !== 404) throw new Error(`expected 404, got ${r1.res.statusCode}`);
+          const body1 = r1.body.toString();
+          if(!body1.includes('<h1>Deep Catch</h1>')) throw new Error(`expected deep catch, got: ${body1}`);
+
+          // Request at root level should find root CATCH.html
+          const r2 = await httpGet(`http://localhost:${port}/nonexistent`);
+          if(r2.res.statusCode !== 404) throw new Error(`expected 404, got ${r2.res.statusCode}`);
+          const body2 = r2.body.toString();
+          if(!body2.includes('<h1>Root Catch</h1>')) throw new Error(`expected root catch, got: ${body2}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'CATCH fallback walks up multiple levels': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+        await write(dir, 'public/CATCH.html', '<h1>Root Catch</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          // Deep nested request should walk up to root CATCH.html
+          const r = await httpGet(`http://localhost:${port}/a/b/c/d/nonexistent`);
+          if(r.res.statusCode !== 404) throw new Error(`expected 404, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          if(!body.includes('<h1>Root Catch</h1>')) throw new Error(`expected root catch, got: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'CATCH.js takes priority over CATCH.html': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        const handler = 'export default async (req, res) => { res.writeHead(404, {"Content-Type":"text/plain"}); res.end("js-catch"); };';
+        await write(dir, 'public/CATCH.js', handler);
+        await write(dir, 'public/CATCH.html', '<h1>HTML Catch</h1>');
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/nonexistent`);
+          const body = r.body.toString();
+          if(body !== 'js-catch') throw new Error(`expected js catch, got: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'CATCH.html takes priority over CATCH.page.html': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        const page = '<page template="default"><content location="main"><h1>Page Catch</h1></content></page>';
+        await write(dir, 'public/default.template.html', template);
+        await write(dir, 'public/CATCH.html', '<h1>HTML Catch</h1>');
+        await write(dir, 'public/CATCH.page.html', page);
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/nonexistent`);
+          if(r.res.statusCode !== 404) throw new Error(`expected 404, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          if(!body.includes('<h1>HTML Catch</h1>')) throw new Error(`expected html catch, got: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'no CATCH fallback returns plain text Not Found': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/nonexistent`);
+          if(r.res.statusCode !== 404) throw new Error(`expected 404, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          if(body !== 'Not Found') throw new Error(`expected plain 'Not Found', got: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'CATCH can respond with any status code (not just 404)': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        const handler = 'export default async (req, res) => { res.writeHead(200, {"Content-Type":"application/json"}); res.end(JSON.stringify({message: "catch all handler", path: req.url})); };';
+        await write(dir, 'public/CATCH.js', handler);
+        await write(dir, 'public/index.html', '<h1>root</h1>');
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/api/data/key/value`);
+          if(r.res.statusCode !== 200) throw new Error(`expected 200, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          const json = JSON.parse(body);
+          if(json.message !== 'catch all handler') throw new Error(`unexpected response: ${body}`);
+          if(!json.path.includes('key/value')) throw new Error(`path params not captured: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  }
+};

package/tests/router-page-html.node-test.js

@@ -0,0 +1,171 @@
+import http from 'http';
+import path from 'path';
+import {withTempDir} from './utils/temp-dir.js';
+import {write} from './utils/file-writer.js';
+import {randomPort} from './utils/port.js';
+import {httpGet} from './utils/http.js';
+import router from '../src/router.js';
+import findFile from '../src/findFile.js';
+
+const template = '<html><body><location name="main" /></body></html>';
+const noop = () => {};
+
+const startServer = async (dir, flags, config = {}) => {
+  await write(dir, `${flags.root}/.config.json`, JSON.stringify(config));
+  const handler = await router({...flags, logging: 0}, noop);
+  const server = http.createServer(handler);
+  const port = randomPort();
+  await new Promise(r => server.listen(port, r));
+  await new Promise(r => setTimeout(r, 30));
+  return {server, port};
+};
+
+const toAbs = (root, p) => path.join(root, p);
+
+export default {
+  'findFile resolves METHOD.page.html after METHOD.html': async ({pass, fail}) => {
+    const root = path.join(process.cwd(), 'tmp-root');
+    const files = [
+      toAbs(root, 'docs/GET.page.html'),
+      toAbs(root, 'docs/index.html')
+    ];
+    const [file] = await findFile(files, root, '/docs', 'GET', noop);
+    if(!file || path.basename(file) !== 'GET.page.html') return fail(`expected GET.page.html, got ${file ? path.basename(file) : 'none'}`);
+    pass();
+  },
+
+  'findFile prefers METHOD.js over METHOD.page.html': async ({pass, fail}) => {
+    const root = path.join(process.cwd(), 'tmp-root');
+    const files = [
+      toAbs(root, 'api/GET.js'),
+      toAbs(root, 'api/GET.page.html')
+    ];
+    const [file] = await findFile(files, root, '/api', 'GET', noop);
+    if(!file || path.basename(file) !== 'GET.js') return fail(`expected GET.js, got ${file ? path.basename(file) : 'none'}`);
+    pass();
+  },
+
+  'findFile prefers METHOD.html over METHOD.page.html': async ({pass, fail}) => {
+    const root = path.join(process.cwd(), 'tmp-root');
+    const files = [
+      toAbs(root, 'info/GET.html'),
+      toAbs(root, 'info/GET.page.html')
+    ];
+    const [file] = await findFile(files, root, '/info', 'GET', noop);
+    if(!file || path.basename(file) !== 'GET.html') return fail(`expected GET.html, got ${file ? path.basename(file) : 'none'}`);
+    pass();
+  },
+
+  'findFile resolves index.page.html': async ({pass, fail}) => {
+    const root = path.join(process.cwd(), 'tmp-root');
+    const files = [toAbs(root, 'section/index.page.html')];
+    const [file] = await findFile(files, root, '/section', 'GET', noop);
+    if(!file || path.basename(file) !== 'index.page.html') return fail(`expected index.page.html, got ${file ? path.basename(file) : 'none'}`);
+    pass();
+  },
+
+  'findFile prefers index.js over index.page.html': async ({pass, fail}) => {
+    const root = path.join(process.cwd(), 'tmp-root');
+    const files = [
+      toAbs(root, 'section/index.js'),
+      toAbs(root, 'section/index.page.html')
+    ];
+    const [file] = await findFile(files, root, '/section', 'GET', noop);
+    if(!file || path.basename(file) !== 'index.js') return fail(`expected index.js, got ${file ? path.basename(file) : 'none'}`);
+    pass();
+  },
+
+  'findFile resolves dynamic route with METHOD.page.html': async ({pass, fail}) => {
+    const root = path.join(process.cwd(), 'tmp-root');
+    const files = [toAbs(root, 'users/[id]/GET.page.html')];
+    const [file, params] = await findFile(files, root, '/users/42', 'GET', noop);
+    if(!file || path.basename(file) !== 'GET.page.html') return fail(`expected GET.page.html, got ${file ? path.basename(file) : 'none'}`);
+    if(params.id !== '42') return fail(`expected id=42, got ${params.id}`);
+    pass();
+  },
+
+  'router serves GET.page.html rendered through templating': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        const page = '<page template="default"><content location="main"><h1>Page Route</h1></content></page>';
+        await write(dir, 'public/default.template.html', template);
+        await write(dir, 'public/api/GET.page.html', page);
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/api`);
+          if(r.res.statusCode !== 200) throw new Error(`expected 200, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          if(!body.includes('<h1>Page Route</h1>')) throw new Error(`missing page content: ${body}`);
+          if(!body.includes('<html>')) throw new Error(`missing template wrapper: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'router serves index.page.html for directory request': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        const page = '<page template="default"><content location="main"><h1>Dir Index</h1></content></page>';
+        await write(dir, 'public/default.template.html', template);
+        await write(dir, 'public/section/index.page.html', page);
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/section`);
+          if(r.res.statusCode !== 200) throw new Error(`expected 200, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          if(!body.includes('<h1>Dir Index</h1>')) throw new Error(`missing page content: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'router prefers GET.js over GET.page.html': async ({pass, fail}) => {
+    try {
+      await withTempDir(async (dir) => {
+        const page = '<page template="default"><content location="main"><h1>Page</h1></content></page>';
+        const routeJs = 'export default async (req, res) => { res.json({source: "js"}); };';
+        await write(dir, 'public/default.template.html', template);
+        await write(dir, 'public/api/GET.js', routeJs);
+        await write(dir, 'public/api/GET.page.html', page);
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const {server, port} = await startServer(dir, {root: 'public'});
+
+        try {
+          const r = await httpGet(`http://localhost:${port}/api`);
+          if(r.res.statusCode !== 200) throw new Error(`expected 200, got ${r.res.statusCode}`);
+          const body = r.body.toString();
+          const json = JSON.parse(body);
+          if(json.source !== 'js') throw new Error(`expected js route to win, got: ${body}`);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass();
+    } catch(e) {
+      fail(e.message);
+    }
+  }
+};