kempo-server 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `kempo-server` are documented in this file.
 
+## [2.1.0] - 2026-04-05
+
+### Added
+
+- Custom routes (`customRoutes`) now support file-based routing when the resolved path is a directory. The server looks for route files (`GET.js`, `POST.js`, etc.) and index files (`index.html`) inside directories, matching the same behavior as normal file-based routing.
+- `httpRequest` test utility for making HTTP requests with arbitrary methods.
+
+### Fixed
+
+- Wildcard routes resolving to a directory no longer return `500 EISDIR`. The server now correctly resolves route files or index files within the directory.
+- Exact custom routes pointing to a directory now resolve `index.html` correctly (e.g. `/admin` mapping to a directory containing `index.html`).
+
+---
+
 ## [2.0.0] - 2026-04-04
 
 ### Breaking Changes

package/CONFIG.md

@@ -382,6 +382,18 @@ The `*` wildcard matches any single path segment (anything between `/` character
 The `**` wildcard matches any number of path segments, allowing you to map entire directory trees.
 Multiple wildcards can be used in a single route pattern.
 
+**Directory Resolution:**
+When a custom route (basic or wildcard) resolves to a directory, the server looks for files inside it using the same priority as normal file-based routing:
+
+1. `METHOD.js` (e.g. `GET.js`, `POST.js`) — executed as a route module
+2. `METHOD.html` (e.g. `GET.html`) — served as a static file
+3. `index.js` — executed as a route module
+4. `index.html` / `index.htm` — served as a static file
+
+This means wildcard routes like `"/api/**": "../api/**"` fully support API directories containing route files (`GET.js`, `POST.js`, etc.), not just static files.
+
+If the resolved path is a file whose name matches `routeFiles` (e.g. `GET.js`), it will be executed as a route module rather than served as static content.
+
 ### maxRescanAttempts
 
 The maximum number of times to attempt rescanning the file system when a file is not found. Defaults to 3.

package/dist/router.js

@@ -1 +1 @@
-import path from"path";import{readFile}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";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.json",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)}log(`Loading config from: ${configPath}`,3);const configContent=await readFile(configPath,"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||{}}},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;log("Using default config (no config file found)",3)}const dis=new Set(config.disallowedRegex);dis.add("^/\\..*"),dis.add("\\.config$"),dis.add("\\.git/"),config.disallowedRegex=[...dis],log(`Config loaded with ${config.disallowedRegex.length} disallowed patterns`,3);let files=await getFiles(rootPath,config,log);log(`Initial scan found ${files.length} files`,2);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.replace(/\*\*/g,"(.+)").replace(/\*/g,"([^/]+)");return new RegExp(`^${regexPattern}$`).exec(requestPath)},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{const{stat:stat}=await import("fs/promises");try{await stat(customFilePath),log(`Custom route file exists: ${customFilePath}`,4)}catch(e){return log(`Custom route file does NOT exist: ${customFilePath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),void res.end("Custom route file not found")}const fileExtension=path.extname(customFilePath).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(customFilePath,encoding);log(`Serving custom 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}),void res.end(fileContent)}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 fileExtension=path.extname(resolvedFilePath).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(resolvedFilePath,encoding);log(`Serving wildcard file as ${mimeType} (${fileContent.length} bytes)`,4);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;return res.writeHead(200,{"Content-Type":contentType}),void res.end(fileContent)}catch(error){if("ENOENT"!==error.code)return log(`Error serving wildcard route ${requestPath}: ${error.message}`,1),enhancedResponse.writeHead(500,{"Content-Type":"text/plain"}),void enhancedResponse.end("Internal Server Error");log(`Wildcard route file not found: ${requestPath}`,2)}}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}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";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.json",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)}log(`Loading config from: ${configPath}`,3);const configContent=await readFile(configPath,"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||{}}},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;log("Using default config (no config file found)",3)}const dis=new Set(config.disallowedRegex);dis.add("^/\\..*"),dis.add("\\.config$"),dis.add("\\.git/"),config.disallowedRegex=[...dis],log(`Config loaded with ${config.disallowedRegex.length} disallowed patterns`,3);let files=await getFiles(rootPath,config,log);log(`Initial scan found ${files.length} files`,2);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.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)=>{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,{}),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)},serveCustomRoutePath=async(resolvedFilePath,req,res)=>{let fileStat;try{fileStat=await stat(resolvedFilePath)}catch(e){if("ENOENT"===e.code)return null;throw e}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(resolvedFilePath,candidate);try{await stat(candidatePath)}catch{continue}return config.routeFiles.includes(candidate)?(log(`Executing route file: ${candidatePath}`,2),await executeRouteModule(candidatePath,req,res),!0):(log(`Serving index file: ${candidatePath}`,2),await serveStaticCustomFile(candidatePath,res),!0)}return null}const fileName=path.basename(resolvedFilePath);return config.routeFiles.includes(fileName)?(log(`Executing route file: ${resolvedFilePath}`,2),await executeRouteModule(resolvedFilePath,req,res),!0):(await serveStaticCustomFile(resolvedFilePath,res),!0)},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))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{if(await serveCustomRoutePath(resolvedFilePath,req,res))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};

package/docs/configuration.html

@@ -118,6 +118,17 @@
 }</code></pre>
     <p>Now requests to <code>/dist/app.js</code> will serve <code>../src/app.js</code> (the unminified source), while production uses the actual <code>dist/</code> files.</p>
 
+    <h4>Directory Resolution</h4>
+    <p>When a custom route (basic or wildcard) resolves to a directory, the server looks for files inside it using the same priority as normal file-based 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 a static file</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 a static file</li>
+    </ol>
+    <p>This means wildcard routes like <code>"/api/**": "../api/**"</code> fully support API directories containing route files (<code>GET.js</code>, <code>POST.js</code>, etc.), not just static files.</p>
+    <p>If the resolved path is a file whose name matches <code>routeFiles</code> (e.g. <code>GET.js</code>), it will be executed as a route module rather than served as static content.</p>
+
     <h3 id="maxRescanAttempts">maxRescanAttempts</h3>
     <p>The maximum number of times to attempt rescanning the file system when a file is not found. Defaults to 3.</p>
     <pre><code class="hljs json">{<br />  <span class="hljs-attr">"maxRescanAttempts"</span>: <span class="hljs-number">3</span><br />}</code></pre>

package/docs/routing.html

@@ -71,6 +71,16 @@
 
     <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>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>index.js</code> &mdash; executed as a route module</li>
+      <li><code>index.html</code> / <code>index.htm</code> &mdash; served as static</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>
   </main>
   <div style="height:25vh"></div>
 </body>

package/llm.txt

@@ -96,7 +96,7 @@ export default async (req, res) => {
 }
 ```
 
-`customRoutes` values: exact path string (redirect) or `{ "file": "/path.js", "params": {} }` (custom handler file). `*` matches one path segment; `**` matches multiple.
+`customRoutes` values: exact path string or wildcard pattern mapped to a file or directory path. `*` matches one path segment; `**` matches multiple. When a route resolves to a directory, the server looks for route files inside it using the same priority as normal routing: `METHOD.js`, `METHOD.html`, `index.js`, `index.html`.
 
 ## Custom Middleware
 

package/package.json

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

package/src/router.js

@@ -1,5 +1,5 @@
 import path from 'path';
-import { readFile } from 'fs/promises';
+import { readFile, stat } from 'fs/promises';
 import { pathToFileURL } from 'url';
 import defaultConfig from './defaultConfig.js';
 import getFiles from './getFiles.js';
@@ -225,6 +225,108 @@ export default async (flags, log) => {
     return null;
   };
 
+  /*
+    Custom Route Helpers
+  */
+  const serveStaticCustomFile = async (filePath, res) => {
+    const fileExtension = path.extname(filePath).toLowerCase().slice(1);
+    const mimeConfig = config.allowedMimes[fileExtension];
+    let mimeType, encoding;
+    if(typeof mimeConfig === 'string') {
+      mimeType = mimeConfig;
+      encoding = mimeType.startsWith('text/') ? 'utf8' : undefined;
+    } else {
+      mimeType = mimeConfig?.mime || 'application/octet-stream';
+      encoding = mimeConfig?.encoding === 'utf8' ? 'utf8' : undefined;
+    }
+    const fileContent = await readFile(filePath, encoding);
+    log(`Serving custom file as ${mimeType} (${fileContent.length} bytes)`, 2);
+    const contentType = encoding === 'utf8' && mimeType.startsWith('text/')
+      ? `${mimeType}; charset=utf-8`
+      : mimeType;
+    res.writeHead(200, { 'Content-Type': contentType });
+    res.end(fileContent);
+  };
+
+  const executeRouteModule = async (filePath, req, res) => {
+    let module;
+    if(moduleCache && config.cache?.enabled) {
+      const fileStats = await stat(filePath);
+      module = moduleCache.get(filePath, fileStats);
+      if(!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(typeof module.default !== 'function') {
+      log(`Route file does not export a function: ${filePath}`, 0);
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+      res.end('Route file does not export a function');
+      return;
+    }
+    const enhancedReq = createRequestWrapper(req, {});
+    const enhancedRes = createResponseWrapper(res);
+    const rawBody = await readRawBody(req);
+    enhancedReq._rawBody = rawBody;
+    enhancedReq.body = parseBody(rawBody, req.headers['content-type']);
+    if(moduleCache) enhancedReq._kempoCache = moduleCache;
+    await module.default(enhancedReq, enhancedRes);
+  };
+
+  // Resolves a custom route path that may be a file or directory.
+  // Returns true if handled, null if path not found.
+  const serveCustomRoutePath = async (resolvedFilePath, req, res) => {
+    let fileStat;
+    try {
+      fileStat = await stat(resolvedFilePath);
+    } catch(e) {
+      if(e.code === 'ENOENT') return null;
+      throw e;
+    }
+
+    if(fileStat.isDirectory()) {
+      const methodUpper = req.method.toUpperCase();
+      const candidates = [
+        `${methodUpper}.js`,
+        `${methodUpper}.html`,
+        'index.js',
+        'index.html',
+        'index.htm'
+      ];
+      for(const candidate of candidates) {
+        const candidatePath = path.join(resolvedFilePath, candidate);
+        try {
+          await stat(candidatePath);
+        } catch {
+          continue;
+        }
+        if(config.routeFiles.includes(candidate)) {
+          log(`Executing route file: ${candidatePath}`, 2);
+          await executeRouteModule(candidatePath, req, res);
+          return true;
+        }
+        log(`Serving index file: ${candidatePath}`, 2);
+        await serveStaticCustomFile(candidatePath, res);
+        return true;
+      }
+      return null;
+    }
+
+    const fileName = path.basename(resolvedFilePath);
+    if(config.routeFiles.includes(fileName)) {
+      log(`Executing route file: ${resolvedFilePath}`, 2);
+      await executeRouteModule(resolvedFilePath, req, res);
+      return true;
+    }
+    await serveStaticCustomFile(resolvedFilePath, res);
+    return true;
+  };
+
   // Track 404 attempts to avoid unnecessary rescans
   const rescanAttempts = new Map(); // path -> attempt count
   const dynamicNoRescanPaths = new Set(); // paths that have exceeded max attempts
@@ -346,37 +448,13 @@ export default async (flags, log) => {
         const customFilePath = customRoutes.get(matchedKey);
         log(`Serving custom route: ${normalizedRequestPath} -> ${customFilePath}`, 3);
         try {
-          const { stat } = await import('fs/promises');
-          try {
-            await stat(customFilePath);
-            log(`Custom route file exists: ${customFilePath}`, 4);
-          } catch (e) {
-            log(`Custom route file does NOT exist: ${customFilePath}`, 1);
-            res.writeHead(404, { 'Content-Type': 'text/plain' });
-            res.end('Custom route file not found');
-            return;
-          }
-          const fileExtension = path.extname(customFilePath).toLowerCase().slice(1);
-          const mimeConfig = config.allowedMimes[fileExtension];
-          let mimeType, encoding;
-          if (typeof mimeConfig === 'string') {
-            mimeType = mimeConfig;
-            // Default to UTF-8 for text MIME types
-            encoding = mimeType.startsWith('text/') ? 'utf8' : undefined;
-          } else {
-            mimeType = mimeConfig?.mime || 'application/octet-stream';
-            encoding = mimeConfig?.encoding === 'utf8' ? 'utf8' : undefined;
-          }
-          const fileContent = await readFile(customFilePath, encoding);
-          log(`Serving custom file as ${mimeType} (${fileContent.length} bytes)`, 2);
-          // Add charset=utf-8 for text MIME types when using UTF-8 encoding
-          const contentType = encoding === 'utf8' && mimeType.startsWith('text/') 
-            ? `${mimeType}; charset=utf-8` 
-            : mimeType;
-          res.writeHead(200, { 'Content-Type': contentType });
-          res.end(fileContent);
-          return; // Successfully served custom route
-        } catch (error) {
+          const result = await serveCustomRoutePath(customFilePath, req, res);
+          if(result) return;
+          log(`Custom route path not found: ${customFilePath}`, 1);
+          res.writeHead(404, { 'Content-Type': 'text/plain' });
+          res.end('Custom route file not found');
+          return;
+        } catch(error) {
           log(`Error serving custom route ${normalizedRequestPath}: ${error.message}`, 1);
           res.writeHead(500, { 'Content-Type': 'text/plain' });
           res.end('Internal Server Error');
@@ -386,41 +464,18 @@ export default async (flags, log) => {
 
       // Check wildcard routes (allow outside rootPath)
       const wildcardMatch = findWildcardRoute(requestPath);
-      if (wildcardMatch) {
+      if(wildcardMatch) {
         const resolvedFilePath = resolveWildcardPath(wildcardMatch.filePath, wildcardMatch.matches);
         log(`Serving wildcard route: ${requestPath} -> ${resolvedFilePath}`, 3);
         try {
-          const fileExtension = path.extname(resolvedFilePath).toLowerCase().slice(1);
-          const mimeConfig = config.allowedMimes[fileExtension];
-          let mimeType, encoding;
-          if (typeof mimeConfig === 'string') {
-            mimeType = mimeConfig;
-            // Default to UTF-8 for text MIME types
-            encoding = mimeType.startsWith('text/') ? 'utf8' : undefined;
-          } else {
-            mimeType = mimeConfig?.mime || 'application/octet-stream';
-            encoding = mimeConfig?.encoding === 'utf8' ? 'utf8' : undefined;
-          }
-          const fileContent = await readFile(resolvedFilePath, encoding);
-          log(`Serving wildcard file as ${mimeType} (${fileContent.length} bytes)`, 4);
-          // Add charset=utf-8 for text MIME types when using UTF-8 encoding
-          const contentType = encoding === 'utf8' && mimeType.startsWith('text/') 
-            ? `${mimeType}; charset=utf-8` 
-            : mimeType;
-          res.writeHead(200, { 'Content-Type': contentType });
-          res.end(fileContent);
-          return; // Successfully served wildcard route
-        } catch (error) {
-          // Check if it's a file not found error
-          if (error.code === 'ENOENT') {
-            log(`Wildcard route file not found: ${requestPath}`, 2);
-            // Let it fall through to normal 404 handling
-          } else {
-            log(`Error serving wildcard route ${requestPath}: ${error.message}`, 1);
-            enhancedResponse.writeHead(500, { 'Content-Type': 'text/plain' });
-            enhancedResponse.end('Internal Server Error');
-            return;
-          }
+          const result = await serveCustomRoutePath(resolvedFilePath, req, res);
+          if(result) return;
+          log(`Wildcard route path not found: ${requestPath}`, 2);
+        } catch(error) {
+          log(`Error serving wildcard route ${requestPath}: ${error.message}`, 1);
+          enhancedResponse.writeHead(500, { 'Content-Type': 'text/plain' });
+          enhancedResponse.end('Internal Server Error');
+          return;
         }
       }
       

package/tests/router-custom-route-dirs.node-test.js

@@ -0,0 +1,319 @@
+import http from 'http';
+import {withTempDir} from './utils/temp-dir.js';
+import {write} from './utils/file-writer.js';
+import {randomPort} from './utils/port.js';
+import {httpGet, httpRequest} from './utils/http.js';
+import router from '../src/router.js';
+
+export default {
+  'wildcard route resolves GET.js in directory': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'api/auth/session/GET.js',
+          `export default (req, res) => { res.writeHead(200, {'Content-Type':'application/json'}); res.end('{"user":"test"}'); };`
+        );
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/api/**': '../api/**' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpGet(`http://localhost:${port}/api/auth/session`);
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 200) throw new Error('expected 200, got ' + r1.res.statusCode);
+          const body = JSON.parse(r1.body.toString());
+          if(body.user !== 'test') throw new Error('unexpected body: ' + r1.body.toString());
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('wildcard route resolves GET.js in directory');
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'wildcard route resolves POST.js in directory': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'api/users/POST.js',
+          `export default (req, res) => { res.writeHead(201, {'Content-Type':'application/json'}); res.end('{"created":true}'); };`
+        );
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/api/**': '../api/**' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpRequest(`http://localhost:${port}/api/users`, 'POST', '{"name":"alice"}');
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 201) throw new Error('expected 201, got ' + r1.res.statusCode);
+          const body = JSON.parse(r1.body.toString());
+          if(!body.created) throw new Error('unexpected body: ' + r1.body.toString());
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('wildcard route resolves POST.js in directory');
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'wildcard route resolves index.html in directory': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'app/admin/index.html', '<h1>Admin Panel</h1>');
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/app/**': '../app/**' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpGet(`http://localhost:${port}/app/admin`);
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 200) throw new Error('expected 200, got ' + r1.res.statusCode);
+          if(!r1.body.toString().includes('Admin Panel')) throw new Error('missing content');
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('wildcard route resolves index.html in directory');
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'exact custom route resolves GET.js in directory': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'api/status/GET.js',
+          `export default (req, res) => { res.writeHead(200, {'Content-Type':'application/json'}); res.end('{"ok":true}'); };`
+        );
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/status': '../api/status' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpGet(`http://localhost:${port}/status`);
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 200) throw new Error('expected 200, got ' + r1.res.statusCode);
+          const body = JSON.parse(r1.body.toString());
+          if(!body.ok) throw new Error('unexpected body');
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('exact custom route resolves GET.js in directory');
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'exact custom route resolves index.html in directory': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'site/dashboard/index.html', '<h1>Dashboard</h1>');
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/dashboard': '../site/dashboard' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpGet(`http://localhost:${port}/dashboard`);
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 200) throw new Error('expected 200, got ' + r1.res.statusCode);
+          if(!r1.body.toString().includes('Dashboard')) throw new Error('missing content');
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('exact custom route resolves index.html in directory');
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'wildcard route still serves static files': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'assets/style.css', 'body { color: red; }');
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/assets/**': '../assets/**' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpGet(`http://localhost:${port}/assets/style.css`);
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 200) throw new Error('expected 200');
+          if(!r1.body.toString().includes('color: red')) throw new Error('wrong content');
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('wildcard route still serves static files');
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'wildcard directory with no matching files returns 404': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'api/empty/.gitkeep', '');
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/api/**': '../api/**' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpGet(`http://localhost:${port}/api/empty`);
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 404) throw new Error('expected 404, got ' + r1.res.statusCode);
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('wildcard directory with no matching files returns 404');
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'route file GET.js takes priority over index.html in directory': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'api/data/GET.js',
+          `export default (req, res) => { res.writeHead(200, {'Content-Type':'application/json'}); res.end('{"from":"route"}'); };`
+        );
+        await write(dir, 'api/data/index.html', '<h1>Index</h1>');
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/api/**': '../api/**' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpGet(`http://localhost:${port}/api/data`);
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 200) throw new Error('expected 200');
+          const body = JSON.parse(r1.body.toString());
+          if(body.from !== 'route') throw new Error('GET.js should take priority over index.html');
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('route file GET.js takes priority over index.html');
+    } catch(e) {
+      fail(e.message);
+    }
+  },
+
+  'wildcard route executes route file directly mapped to a file': async ({pass, fail, log}) => {
+    try {
+      await withTempDir(async (dir) => {
+        await write(dir, 'handlers/GET.js',
+          `export default (req, res) => { res.writeHead(200, {'Content-Type':'text/plain'}); res.end('handled'); };`
+        );
+        await write(dir, 'docs/index.html', '<html></html>');
+        await write(dir, 'docs/.config.json', JSON.stringify({
+          customRoutes: { '/handler': '../handlers/GET.js' }
+        }));
+
+        const prev = process.cwd();
+        process.chdir(dir);
+        const handler = await router({root: 'docs', logging: 0}, () => {});
+        const server = http.createServer(handler);
+        const port = randomPort();
+        await new Promise(r => server.listen(port, r));
+        await new Promise(r => setTimeout(r, 50));
+
+        try {
+          const r1 = await httpGet(`http://localhost:${port}/handler`);
+          log('status: ' + r1.res.statusCode);
+          if(r1.res.statusCode !== 200) throw new Error('expected 200');
+          if(r1.body.toString() !== 'handled') throw new Error('expected route execution');
+        } finally {
+          server.close();
+          process.chdir(prev);
+        }
+      });
+      pass('exact custom route executes route file directly');
+    } catch(e) {
+      fail(e.message);
+    }
+  }
+};

package/tests/utils/http.js

@@ -6,4 +6,25 @@ export const httpGet = (url) => new Promise((resolve, reject) => {
       res.on('end', () => resolve({res, body: Buffer.concat(chunks)}));
     }).on('error', reject);
   }).catch(reject);
+});
+
+export const httpRequest = (url, method, body) => new Promise((resolve, reject) => {
+  import('http').then(({request}) => {
+    const parsed = new URL(url);
+    const opts = {
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.pathname + parsed.search,
+      method
+    };
+    if(body) opts.headers = { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) };
+    const req = request(opts, res => {
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => resolve({res, body: Buffer.concat(chunks)}));
+    });
+    req.on('error', reject);
+    if(body) req.write(body);
+    req.end();
+  }).catch(reject);
 });