@luckystack/server 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `collectOverlayEntries(packageDir)` — the single owner of what a `luckystack/<pkg>/` folder contributes at boot, exported so `scripts/bundleServer.mjs` decides identically instead of reimplementing the walk (ADR 0047).
+
+### Fixed
+
+- Test files in a `luckystack/<pkg>/` overlay folder are no longer imported at boot or bundled into the production server. A test file that only performs side effects (registering a stub adapter, say) previously ran in production without failing loudly. Covers `.tests.` / `.test.` / `.spec.` plus `__tests__` / `__mocks__` folders.
+- A subdirectory inside an overlay package folder is now reported instead of skipped in silence. The walk is flat by design, so overlay code parked one level down never ran and nothing pointed at it.
+
+- Composed presets accept a repeated NESTED function namespace. Equivalence is now checked recursively, so a namespace object rebuilt per preset (any function module living in a subdirectory of a `serverFunctionDirs` root) no longer reads as a differing implementation and rejects the compose at boot. A genuinely differing leaf implementation still fails closed.
+
 ## [0.8.4] - 2026-08-17
 
 ### Changed

package/CLAUDE.md

@@ -29,6 +29,7 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 | `RunningLuckyStackServer.stop(options?)` / `.close(options?)` | Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the core `preServerStop` hook, flushes error-trackers (bounded by a per-step timeout race), then closes io + http + the Redis-adapter pub/sub clients. Each step isolated + time-bounded so one hanging step can't stall shutdown. Idempotent. `options`: `{ reason?, timeoutMs? }` (default `timeoutMs` 10000). | -> docs/create-server.md |
 | `bootstrapLuckyStack(options)` | High-level entry: auto-imports `luckystack/<pkg>/*.ts` overlay in topological order, then delegates to `createLuckyStackServer`. An overlay file that fails to import (classic: it imports a package removed via `luckystack remove`) aborts boot with an ACTIONABLE error naming the file, instead of a raw ERR_MODULE_NOT_FOUND. | -> docs/create-server.md |
 | `OVERLAY_ORDER` (exported const) | The canonical overlay walk order (`core, deploy, login, email, sentry, presence, cron, docs-ui, server`). Exported so the consumer's `scripts/bundleServer.mjs` imports it at build time — a hardcoded bundler copy once silently dropped the cron slot from prod; `overlayOrderParity.test.ts` pins the bundlers' fallback lists to this. | -> docs/create-server.md |
+| `collectOverlayEntries(packageDir)` | Single owner of what one `luckystack/<pkg>/` folder contributes: `{ fileNames, ignoredDirectoryNames }`. `index.*` first, then the rest alphabetically; `.ts`/`.js` only; **test files excluded** (`.tests.`/`.test.`/`.spec.`, plus `__tests__`/`__mocks__` folders) so they never boot or reach the production bundle. The walk is FLAT — any other subdirectory comes back in `ignoredDirectoryNames` and the loader warns, instead of dropping overlay code in silence. Exported so `scripts/bundleServer.mjs` decides identically. ADR 0047. | -> docs/create-server.md |
 | `registerOverlayLoader(loader)` | Production-bundle seam: the server bundler (`scripts/bundleServer.mjs`) generates an entry that statically imports the overlay files and registers this loader; `bootstrapLuckyStack` then runs it INSTEAD of the runtime `.ts` folder walk (plain `node` cannot import `.ts` — ERR_UNKNOWN_FILE_EXTENSION). | -> docs/create-server.md |
 | `verifyBootstrap(requirements?)` | Pre-flight check for ProjectConfig / DeployConfig / ServicesConfig / OAuth / RuntimeMapsProvider / LocalizedNormalizer. Throws one descriptive `Error`. | -> docs/create-server.md |
 | `parseServerArgv(argv)` | Pure parser: validates positional `<bundles> [port]` and returns `{ bundles, port }`. Throws on malformed input. | -> docs/argv-parsing.md |

package/dist/index.d.ts

@@ -197,6 +197,23 @@ interface BootstrapLuckyStackOptions extends CreateLuckyStackServerOptions {
 declare const OVERLAY_ORDER: string[];
 type OverlayLoader = () => Promise<void>;
 declare const registerOverlayLoader: (loader: OverlayLoader) => void;
+interface OverlayEntries {
+    /** Files to import, in load order: `index.*` first, then the rest alphabetically. */
+    fileNames: string[];
+    /**
+     * Subdirectories the flat walk skipped, minus conventional test folders.
+     * The caller warns about these — silently dropping them meant overlay code
+     * one level down simply never ran, with nothing to point at.
+     */
+    ignoredDirectoryNames: string[];
+}
+/**
+ * Decide what a single overlay package folder contributes. Exported because
+ * both the runtime walk here and `scripts/bundleServer.mjs` must agree exactly:
+ * a file the bundler includes but the loader skips (or the reverse) is a
+ * dev/prod divergence, which is the defect class ADR 0046 exists for.
+ */
+declare const collectOverlayEntries: (packageDir: string) => OverlayEntries;
 declare const bootstrapLuckyStack: (options?: BootstrapLuckyStackOptions) => Promise<RunningLuckyStackServer>;
 
 interface BootstrapRequirements {
@@ -308,4 +325,4 @@ declare const registerSecurityHeaders: (builder: SecurityHeadersBuilder | null)
 /** Read the active builder (or null). */
 declare const getSecurityHeadersBuilder: () => SecurityHeadersBuilder | null;
 
-export { type BootstrapLuckyStackOptions, type BootstrapRequirements, type CreateLuckyStackServerOptions, type CustomRouteHandler, type CustomRoutePhase, type FaviconHandler, type GeneratedRuntimeMapsModule, OVERLAY_ORDER, type OnLocationUpdatePayload, type OnSocketConnectPayload, type OnSocketDisconnectPayload, type OriginExemptMatcher, type ParsedServerArgv, type PostRoomJoinPayload, type PostRoomLeavePayload, type PreRoomJoinPayload, type PreRoomLeavePayload, type ProdRuntimeMapsLoaderOptions, type RegisterCustomRouteOptions, type RouteContext, type RunningLuckyStackServer, type SecurityHeadersBuilder, type StaticFileHandler, type StopLuckyStackServerOptions, applyServerArgv, bootstrapLuckyStack, clearCustomRoutes, clearOriginExemptPaths, createLuckyStackServer, createProdRuntimeMapsProvider, getCustomRoutes, getOriginExemptPaths, getParsedBundles, getParsedPort, getPreParamsCustomRoutes, getSecurityHeadersBuilder, isOriginExemptPath, parseServerArgv, registerCustomRoute, registerOriginExemptPath, registerOverlayLoader, registerProdRuntimeMapsProvider, registerSecurityHeaders, verifyBootstrap };
+export { type BootstrapLuckyStackOptions, type BootstrapRequirements, type CreateLuckyStackServerOptions, type CustomRouteHandler, type CustomRoutePhase, type FaviconHandler, type GeneratedRuntimeMapsModule, OVERLAY_ORDER, type OnLocationUpdatePayload, type OnSocketConnectPayload, type OnSocketDisconnectPayload, type OriginExemptMatcher, type OverlayEntries, type ParsedServerArgv, type PostRoomJoinPayload, type PostRoomLeavePayload, type PreRoomJoinPayload, type PreRoomLeavePayload, type ProdRuntimeMapsLoaderOptions, type RegisterCustomRouteOptions, type RouteContext, type RunningLuckyStackServer, type SecurityHeadersBuilder, type StaticFileHandler, type StopLuckyStackServerOptions, applyServerArgv, bootstrapLuckyStack, clearCustomRoutes, clearOriginExemptPaths, collectOverlayEntries, createLuckyStackServer, createProdRuntimeMapsProvider, getCustomRoutes, getOriginExemptPaths, getParsedBundles, getParsedPort, getPreParamsCustomRoutes, getSecurityHeadersBuilder, isOriginExemptPath, parseServerArgv, registerCustomRoute, registerOriginExemptPath, registerOverlayLoader, registerProdRuntimeMapsProvider, registerSecurityHeaders, verifyBootstrap };

package/dist/index.js

@@ -2156,7 +2156,7 @@ var areEquivalentFunctionEntries = (left, right) => {
   if (!isRuntimeMapRecord(left) || !isRuntimeMapRecord(right)) return false;
   const leftKeys = Object.keys(left);
   const rightKeys = Object.keys(right);
-  return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && Object.is(left[key], right[key]));
+  return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && areEquivalentFunctionEntries(left[key], right[key]));
 };
 var mergeInto = (target, source, kind, fromPreset, keyOrigin) => {
   for (const key of Object.keys(source)) {
@@ -2520,7 +2520,7 @@ var createLuckyStackServer = async (options = {}) => {
 import path3 from "path";
 import fs2 from "fs";
 import { pathToFileURL } from "url";
-import { ROOT_DIR, tryCatch as tryCatch11 } from "@luckystack/core";
+import { ROOT_DIR, tryCatch as tryCatch11, getLogger as getLogger14, isTestFile, isTestDirectory } from "@luckystack/core";
 var OVERLAY_ORDER = [
   // Core registries first — clients, paths, routing rules. Anything below
   // depends on these being in place.
@@ -2558,6 +2558,24 @@ var registeredOverlayLoader = null;
 var registerOverlayLoader = (loader) => {
   registeredOverlayLoader = loader;
 };
+var collectOverlayEntries = (packageDir) => {
+  const indexCandidates = ["index.ts", "index.js"];
+  const entries = fs2.readdirSync(packageDir, { withFileTypes: true }).toSorted((left, right) => left.name.localeCompare(right.name));
+  const ignoredDirectoryNames = [];
+  const rest = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!isTestDirectory(entry.name)) ignoredDirectoryNames.push(entry.name);
+      continue;
+    }
+    if (indexCandidates.includes(entry.name)) continue;
+    if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".js")) continue;
+    if (isTestFile(entry.name)) continue;
+    rest.push(entry.name);
+  }
+  const indexFileNames = indexCandidates.filter((candidate) => entries.some((entry) => entry.isFile() && entry.name === candidate));
+  return { fileNames: [...indexFileNames, ...rest], ignoredDirectoryNames };
+};
 var loadOverlayFolder = async (overlayRoot) => {
   const overlayAbs = path3.isAbsolute(overlayRoot) ? overlayRoot : path3.join(ROOT_DIR, overlayRoot);
   if (!fs2.existsSync(overlayAbs)) {
@@ -2566,15 +2584,14 @@ var loadOverlayFolder = async (overlayRoot) => {
   for (const packageName of OVERLAY_ORDER) {
     const packageDir = path3.join(overlayAbs, packageName);
     if (!fs2.existsSync(packageDir)) continue;
-    const indexCandidates = ["index.ts", "index.js"];
-    for (const candidate of indexCandidates) {
-      await importIfExists(path3.join(packageDir, candidate));
+    const { fileNames, ignoredDirectoryNames } = collectOverlayEntries(packageDir);
+    for (const directoryName of ignoredDirectoryNames) {
+      getLogger14().warn(
+        `[luckystack:overlay] ignoring \`${overlayRoot}/${packageName}/${directoryName}/\` \u2014 the overlay walk does not recurse. Move the file(s) up into \`${overlayRoot}/${packageName}/\`, or import them from a file that is there.`
+      );
     }
-    const entries = fs2.readdirSync(packageDir).toSorted();
-    for (const entry of entries) {
-      if (indexCandidates.includes(entry)) continue;
-      if (!entry.endsWith(".ts") && !entry.endsWith(".js")) continue;
-      await importIfExists(path3.join(packageDir, entry));
+    for (const fileName of fileNames) {
+      await importIfExists(path3.join(packageDir, fileName));
     }
   }
 };
@@ -2614,6 +2631,7 @@ export {
   bootstrapLuckyStack,
   clearCustomRoutes,
   clearOriginExemptPaths,
+  collectOverlayEntries,
   createLuckyStackServer,
   createProdRuntimeMapsProvider,
   getCustomRoutes,