@b9g/platform-node 0.1.13 → 0.1.14-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform-node",
-  "version": "0.1.13",
+  "version": "0.1.14-beta.1",
   "description": "Node.js platform adapter for Shovel with hot reloading and ESBuild integration",
   "keywords": [
     "shovel",
@@ -14,7 +14,7 @@
     "@b9g/cache": "^0.2.0-beta.0",
     "@b9g/http-errors": "^0.2.0-beta.0",
     "@b9g/node-webworker": "^0.2.0-beta.1",
-    "@b9g/platform": "^0.1.13",
+    "@b9g/platform": "^0.1.14-beta.4",
     "@logtape/logtape": "^1.2.0"
   },
   "devDependencies": {
@@ -37,6 +37,14 @@
     "./index.js": {
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
+    },
+    "./platform": {
+      "types": "./src/platform.d.ts",
+      "import": "./src/platform.js"
+    },
+    "./platform.js": {
+      "types": "./src/platform.d.ts",
+      "import": "./src/platform.js"
     }
   }
 }

package/src/index.d.ts

@@ -3,11 +3,9 @@
  *
  * Provides hot reloading, ESBuild integration, and optimized caching for Node.js environments.
  */
-import { BasePlatform, type PlatformConfig, type PlatformDefaults, type Handler, type Server, type ServerOptions, type ServiceWorkerOptions, type ServiceWorkerInstance, type EntryWrapperOptions, type PlatformESBuildConfig, ServiceWorkerPool, CustomLoggerStorage, CustomDatabaseStorage } from "@b9g/platform";
+import { type PlatformDefaults, type Handler, type Server, type ServerOptions, type PlatformESBuildConfig, type EntryPoints, ServiceWorkerPool } from "@b9g/platform";
 import { type ShovelConfig } from "@b9g/platform/runtime";
-import { CustomCacheStorage } from "@b9g/cache";
-import { CustomDirectoryStorage } from "@b9g/filesystem";
-export interface NodePlatformOptions extends PlatformConfig {
+export interface NodePlatformOptions {
     /** Port for development server (default: 3000) */
     port?: number;
     /** Host for development server (default: localhost) */
@@ -20,74 +18,103 @@ export interface NodePlatformOptions extends PlatformConfig {
     config?: ShovelConfig;
 }
 /**
- * Node.js platform implementation
- * ServiceWorker entrypoint loader for Node.js with ESBuild VM system
+ * Node.js ServiceWorkerContainer implementation
+ * Manages ServiceWorker registrations backed by worker threads
  */
-export declare class NodePlatform extends BasePlatform {
+export declare class NodeServiceWorkerContainer extends EventTarget implements ServiceWorkerContainer {
     #private;
-    readonly name: string;
-    constructor(options?: NodePlatformOptions);
+    readonly controller: ServiceWorker | null;
+    oncontrollerchange: ((ev: Event) => unknown) | null;
+    onmessage: ((ev: MessageEvent) => unknown) | null;
+    onmessageerror: ((ev: MessageEvent) => unknown) | null;
+    constructor(platform: NodePlatform);
     /**
-     * Get options for testing
+     * Register a ServiceWorker script
+     * Spawns worker threads and runs lifecycle
      */
-    get options(): {
-        port: number;
-        host: string;
-        cwd: string;
-        workers: number;
-        config?: ShovelConfig;
-    };
+    register(scriptURL: string | URL, options?: RegistrationOptions): Promise<ServiceWorkerRegistration>;
     /**
-     * Get/set worker pool for testing
+     * Get registration for scope
      */
-    get workerPool(): ServiceWorkerPool | undefined;
-    set workerPool(pool: ServiceWorkerPool | undefined);
+    getRegistration(scope?: string): Promise<ServiceWorkerRegistration | undefined>;
     /**
-     * THE MAIN JOB - Load and run a ServiceWorker-style entrypoint in Node.js
-     * Uses Worker threads with coordinated cache storage for isolation and standards compliance
+     * Get all registrations
      */
-    loadServiceWorker(entrypoint: string, options?: ServiceWorkerOptions): Promise<ServiceWorkerInstance>;
+    getRegistrations(): Promise<readonly ServiceWorkerRegistration[]>;
     /**
-     * Create cache storage using config from shovel.json
-     * Used for testing - production uses the generated config module
-     * Merges with runtime defaults (actual class references) for fallback behavior
+     * Start receiving messages (no-op in server context)
      */
-    createCaches(): Promise<CustomCacheStorage>;
+    startMessages(): void;
     /**
-     * Create directory storage using config from shovel.json
-     * Used for testing - production uses the generated config module
-     * Merges with runtime defaults (actual class references) for fallback behavior
+     * Ready promise - resolves when a registration is active
      */
-    createDirectories(): Promise<CustomDirectoryStorage>;
+    get ready(): Promise<ServiceWorkerRegistration>;
     /**
-     * Create logger storage using config from shovel.json
+     * Internal: Get worker pool for request handling
      */
-    createLoggers(): Promise<CustomLoggerStorage>;
+    get pool(): ServiceWorkerPool | undefined;
     /**
-     * Create database storage from declarative config in shovel.json
+     * Internal: Terminate workers and dispose cache storage
      */
-    createDatabases(configOverride?: NodePlatformOptions["config"]): CustomDatabaseStorage | undefined;
+    terminate(): Promise<void>;
+    /**
+     * Internal: Reload workers (for hot reload)
+     */
+    reloadWorkers(entrypoint: string): Promise<void>;
+}
+/**
+ * Node.js platform implementation
+ * ServiceWorker entrypoint loader for Node.js with ESBuild VM system
+ */
+export declare class NodePlatform {
+    #private;
+    readonly name: string;
+    readonly serviceWorker: NodeServiceWorkerContainer;
+    constructor(options?: NodePlatformOptions);
+    /**
+     * Create a worker instance for the pool
+     * Can be overridden for testing
+     */
+    createWorker(entrypoint: string): Promise<Worker>;
+    /**
+     * Start the HTTP server, routing requests to ServiceWorker
+     */
+    listen(): Promise<Server>;
+    /**
+     * Close the server and terminate workers
+     */
+    close(): Promise<void>;
+    /**
+     * Get options for testing
+     */
+    get options(): {
+        port: number;
+        host: string;
+        cwd: string;
+        workers: number;
+        config?: ShovelConfig;
+    };
     /**
-     * SUPPORTING UTILITY - Create HTTP server for Node.js
+     * Create HTTP server for Node.js
      */
     createServer(handler: Handler, options?: ServerOptions): Server;
     /**
      * Reload workers for hot reloading (called by CLI)
+     * @deprecated Use serviceWorker.reloadWorkers() instead
      * @param entrypoint - Path to the new entrypoint (hashed filename)
      */
     reloadWorkers(entrypoint: string): Promise<void>;
     /**
-     * Get virtual entry wrapper for Node.js
+     * Get entry points for bundling.
      *
-     * @param entryPath - Absolute path to user's entrypoint file
-     * @param options - Entry wrapper options
-     * @param options.type - "production" (default) or "worker"
+     * Development mode:
+     * - worker.js: Single worker with message loop (develop command acts as supervisor)
      *
-     * Returns:
-     * - "production": Server entry that loads ServiceWorkerPool
-     * - "worker": Worker entry that sets up runtime and message loop
+     * Production mode:
+     * - index.js: Supervisor that spawns workers and owns the HTTP server
+     * - worker.js: Worker that handles requests via message loop
      */
-    getEntryWrapper(entryPath: string, options?: EntryWrapperOptions): string;
+    getEntryPoints(userEntryPath: string, mode: "development" | "production"): EntryPoints;
     /**
      * Get Node.js-specific esbuild configuration
      *

package/src/index.js

@@ -1,500 +1,190 @@
 /// <reference types="./index.d.ts" />
 // src/index.ts
+import * as HTTP from "node:http";
 import { builtinModules } from "node:module";
 import { tmpdir } from "node:os";
+import * as Path from "node:path";
+import { getLogger } from "@logtape/logtape";
+import { CustomCacheStorage } from "@b9g/cache";
+import { InternalServerError, isHTTPError } from "@b9g/http-errors";
 import {
-  BasePlatform,
-  ServiceWorkerPool,
-  SingleThreadedRuntime,
-  CustomLoggerStorage,
-  CustomDatabaseStorage,
-  createDatabaseFactory
+  ServiceWorkerPool
 } from "@b9g/platform";
 import {
-  createCacheFactory,
-  createDirectoryFactory
+  ShovelServiceWorkerRegistration,
+  kServiceWorker,
+  createCacheFactory
 } from "@b9g/platform/runtime";
-import { CustomCacheStorage } from "@b9g/cache";
 import { MemoryCache } from "@b9g/cache/memory";
-import { CustomDirectoryStorage } from "@b9g/filesystem";
-import { NodeFSDirectory } from "@b9g/filesystem/node-fs";
-import { InternalServerError, isHTTPError } from "@b9g/http-errors";
-import * as HTTP from "http";
-import * as Path from "path";
-import { getLogger } from "@logtape/logtape";
-import { MemoryCache as MemoryCache2 } from "@b9g/cache/memory";
-var entryTemplate = `// Node.js Production Server Entry
-import {tmpdir} from "os"; // For [tmpdir] config expressions
-import * as HTTP from "http";
-import {parentPort} from "worker_threads";
-import {Worker} from "@b9g/node-webworker";
-import {getLogger} from "@logtape/logtape";
-import {configureLogging} from "@b9g/platform/runtime";
-import {config} from "shovel:config"; // Virtual module - resolved at build time
-import Platform from "@b9g/platform-node";
-
-// Configure logging before anything else
-await configureLogging(config.logging);
-
-const logger = getLogger(["shovel", "platform"]);
-
-// Configuration from shovel:config
-const PORT = config.port;
-const HOST = config.host;
-const WORKERS = config.workers;
-
-// Use explicit marker instead of isMainThread
-// This handles the edge case where Shovel's build output is embedded in another worker
-const isShovelWorker = process.env.SHOVEL_SPAWNED_WORKER === "1";
-
-if (WORKERS === 1) {
-	// Single worker mode: worker owns server (same as Bun)
-	// No reusePort needed since there's only one listener
-	if (isShovelWorker) {
-		// Worker thread: runs BOTH server AND ServiceWorker
-		const platform = new Platform({port: PORT, host: HOST, workers: 1});
-
-		// Track resources for shutdown - these get assigned during startup
-		let server;
-		let serviceWorker;
-
-		// Register shutdown handler BEFORE async startup to prevent race condition
-		// where SIGINT arrives during startup and the shutdown message is dropped
-		self.onmessage = async (event) => {
-			if (event.data.type === "shutdown") {
-				logger.info("Worker shutting down");
-				if (server) await server.close();
-				if (serviceWorker) await serviceWorker.dispose();
-				await platform.dispose();
-				postMessage({type: "shutdown-complete"});
-			}
-		};
-
-		const userCodePath = new URL("./server.js", import.meta.url).pathname;
-		serviceWorker = await platform.loadServiceWorker(userCodePath);
-
-		server = platform.createServer(serviceWorker.handleRequest, {
-			port: PORT,
-			host: HOST,
-		});
-		await server.listen();
-
-		// Signal ready to main thread
-		postMessage({type: "ready"});
-		logger.info("Worker started with server", {port: PORT});
-	} else {
-		// Main thread: supervisor only - spawn single worker
-		logger.info("Starting production server (single worker)", {port: PORT});
-
-		// Port availability check - fail fast if port is in use
-		const checkPort = () => new Promise((resolve, reject) => {
-			const testServer = HTTP.createServer();
-			testServer.once("error", reject);
-			testServer.listen(PORT, HOST, () => {
-				testServer.close(() => resolve(undefined));
-			});
-		});
-		try {
-			await checkPort();
-		} catch (err) {
-			logger.error("Port unavailable", {port: PORT, host: HOST, error: err});
-			process.exit(1);
-		}
-
-		let shuttingDown = false;
-
-		const worker = new Worker(new URL(import.meta.url), {
-			env: {SHOVEL_SPAWNED_WORKER: "1"},
-		});
-
-		worker.onmessage = (event) => {
-			if (event.data.type === "ready") {
-				logger.info("Worker ready", {port: PORT});
-			} else if (event.data.type === "shutdown-complete") {
-				logger.info("Worker shutdown complete");
-				process.exit(0);
-			}
-		};
-
-		worker.onerror = (event) => {
-			logger.error("Worker error", {error: event.error});
-		};
-
-		// If a worker crashes, fail fast - let process supervisor handle restarts
-		worker.addEventListener("close", (event) => {
-			if (shuttingDown) return;
-			if (event.code === 0) return; // Clean exit
-			logger.error("Worker crashed", {exitCode: event.code});
-			process.exit(1);
-		});
-
-		// Graceful shutdown
-		const shutdown = () => {
-			shuttingDown = true;
-			logger.info("Shutting down");
-			worker.postMessage({type: "shutdown"});
-		};
-
-		process.on("SIGINT", shutdown);
-		process.on("SIGTERM", shutdown);
-	}
-} else {
-	// Multi-worker mode: main thread owns server (no reusePort in Node.js)
-	// Workers handle ServiceWorker code via postMessage
-	if (isShovelWorker) {
-		// Worker: ServiceWorker only, respond via message loop
-		// This path uses the workerEntryTemplate, not this template
-		throw new Error("Multi-worker mode uses workerEntryTemplate, not entryTemplate");
-	} else {
-		// Main thread: HTTP server + dispatch to worker pool
-		const platform = new Platform({port: PORT, host: HOST, workers: WORKERS});
-		const userCodePath = new URL("./server.js", import.meta.url).pathname;
-
-		logger.info("Starting production server (multi-worker)", {workers: WORKERS, port: PORT});
-
-		// Load ServiceWorker with worker pool
-		const serviceWorker = await platform.loadServiceWorker(userCodePath, {
-			workerCount: WORKERS,
-		});
-
-		// Create HTTP server
-		const server = platform.createServer(serviceWorker.handleRequest, {
-			port: PORT,
-			host: HOST,
-		});
-
-		await server.listen();
-		logger.info("Server running", {url: \`http://\${HOST}:\${PORT}\`, workers: WORKERS});
-
-		// Graceful shutdown
-		const shutdown = async () => {
-			logger.info("Shutting down server");
-			await serviceWorker.dispose();
-			await platform.dispose();
-			await server.close();
-			logger.info("Server stopped");
-			process.exit(0);
-		};
-
-		process.on("SIGINT", shutdown);
-		process.on("SIGTERM", shutdown);
-	}
-}
-`;
-var workerEntryTemplate = `// Worker Entry for ServiceWorkerPool
-// This file sets up the ServiceWorker runtime and message loop
-import {tmpdir} from "os"; // For [tmpdir] config expressions
-import {config} from "shovel:config";
-import {initWorkerRuntime, startWorkerMessageLoop, configureLogging} from "@b9g/platform/runtime";
-
-// Configure logging before anything else
-await configureLogging(config.logging);
-
-// Initialize the worker runtime (installs ServiceWorker globals)
-// Platform defaults and paths are already resolved at build time
-const {registration, databases} = await initWorkerRuntime({config});
-
-// Import user code (registers event handlers via addEventListener)
-// Must use dynamic import to ensure globals are installed first
-await import("__USER_ENTRY__");
-
-// Run ServiceWorker lifecycle
-await registration.install();
-await registration.activate();
-
-// Start the message loop (handles request/response messages from main thread)
-// Pass databases for graceful shutdown (close connections before termination)
-startWorkerMessageLoop({registration, databases});
-`;
 var logger = getLogger(["shovel", "platform"]);
-var NodePlatform = class extends BasePlatform {
-  name;
-  #options;
-  #workerPool;
-  #singleThreadedRuntime;
+var NodeServiceWorkerContainer = class extends EventTarget {
+  #platform;
+  #pool;
   #cacheStorage;
-  #directoryStorage;
-  #databaseStorage;
-  constructor(options = {}) {
-    super(options);
-    this.name = "node";
-    const cwd = options.cwd || process.cwd();
-    this.#options = {
-      port: options.port ?? 3e3,
-      host: options.host ?? "localhost",
-      workers: options.workers ?? 1,
-      cwd,
-      config: options.config
-    };
-  }
-  /**
-   * Get options for testing
-   */
-  get options() {
-    return this.#options;
-  }
-  /**
-   * Get/set worker pool for testing
-   */
-  get workerPool() {
-    return this.#workerPool;
-  }
-  set workerPool(pool) {
-    this.#workerPool = pool;
-  }
-  /**
-   * THE MAIN JOB - Load and run a ServiceWorker-style entrypoint in Node.js
-   * Uses Worker threads with coordinated cache storage for isolation and standards compliance
-   */
-  async loadServiceWorker(entrypoint, options = {}) {
-    const workerCount = options.workerCount ?? this.#options.workers;
-    if (workerCount === 1 && !options.hotReload) {
-      return this.#loadServiceWorkerDirect(entrypoint, options);
-    }
-    return this.#loadServiceWorkerWithPool(entrypoint, options, workerCount);
-  }
-  /**
-   * Load ServiceWorker directly in main thread (single-threaded mode)
-   * No postMessage overhead - maximum performance for production
-   */
-  async #loadServiceWorkerDirect(entrypoint, _options) {
-    const entryPath = Path.resolve(this.#options.cwd, entrypoint);
-    let config = this.#options.config;
-    const configPath = Path.join(Path.dirname(entryPath), "config.js");
-    try {
-      const configModule = await import(configPath);
-      config = configModule.config ?? config;
-    } catch (err) {
-      logger.debug`Using platform config (no config.js): ${err}`;
-    }
-    if (!this.#cacheStorage) {
-      const runtimeCacheDefaults = {
-        default: { impl: MemoryCache }
-      };
-      const userCaches = config?.caches ?? {};
-      const cacheConfigs = {};
-      const allCacheNames = /* @__PURE__ */ new Set([
-        ...Object.keys(runtimeCacheDefaults),
-        ...Object.keys(userCaches)
-      ]);
-      for (const name of allCacheNames) {
-        cacheConfigs[name] = {
-          ...runtimeCacheDefaults[name],
-          ...userCaches[name]
-        };
-      }
-      this.#cacheStorage = new CustomCacheStorage(
-        createCacheFactory({ configs: cacheConfigs })
-      );
-    }
-    if (!this.#directoryStorage) {
-      const runtimeDirDefaults = {
-        server: { impl: NodeFSDirectory },
-        public: { impl: NodeFSDirectory },
-        tmp: { impl: NodeFSDirectory }
-      };
-      const userDirs = config?.directories ?? {};
-      const dirConfigs = {};
-      const allDirNames = /* @__PURE__ */ new Set([
-        ...Object.keys(runtimeDirDefaults),
-        ...Object.keys(userDirs)
-      ]);
-      for (const name of allDirNames) {
-        dirConfigs[name] = { ...runtimeDirDefaults[name], ...userDirs[name] };
-      }
-      this.#directoryStorage = new CustomDirectoryStorage(
-        createDirectoryFactory(dirConfigs)
-      );
-    }
-    if (!this.#databaseStorage) {
-      this.#databaseStorage = this.createDatabases(config);
-    }
-    if (this.#singleThreadedRuntime) {
-      await this.#singleThreadedRuntime.terminate();
-    }
-    if (this.#workerPool) {
-      await this.#workerPool.terminate();
-      this.#workerPool = void 0;
-    }
-    logger.info("Creating single-threaded ServiceWorker runtime", { entryPath });
-    this.#singleThreadedRuntime = new SingleThreadedRuntime({
-      caches: this.#cacheStorage,
-      directories: this.#directoryStorage,
-      databases: this.#databaseStorage,
-      loggers: new CustomLoggerStorage((cats) => getLogger(cats))
+  #registration;
+  #readyPromise;
+  #readyResolve;
+  // Standard ServiceWorkerContainer properties
+  controller;
+  oncontrollerchange;
+  onmessage;
+  onmessageerror;
+  constructor(platform) {
+    super();
+    this.#platform = platform;
+    this.#readyPromise = new Promise((resolve2) => {
+      this.#readyResolve = resolve2;
     });
-    await this.#singleThreadedRuntime.init();
-    await this.#singleThreadedRuntime.load(entryPath);
-    const runtime = this.#singleThreadedRuntime;
-    const platform = this;
-    const instance = {
-      runtime,
-      handleRequest: async (request) => {
-        if (!platform.#singleThreadedRuntime) {
-          throw new Error("SingleThreadedRuntime not initialized");
-        }
-        return platform.#singleThreadedRuntime.handleRequest(request);
-      },
-      install: async () => {
-        logger.info("ServiceWorker installed", { method: "single_threaded" });
-      },
-      activate: async () => {
-        logger.info("ServiceWorker activated", { method: "single_threaded" });
-      },
-      get ready() {
-        return runtime?.ready ?? false;
-      },
-      dispose: async () => {
-        if (platform.#singleThreadedRuntime) {
-          await platform.#singleThreadedRuntime.terminate();
-          platform.#singleThreadedRuntime = void 0;
-        }
-        logger.info("ServiceWorker disposed", {});
-      }
-    };
-    logger.info("ServiceWorker loaded", {
-      features: ["single_threaded", "no_postmessage_overhead"]
-    });
-    return instance;
+    this.controller = null;
+    this.oncontrollerchange = null;
+    this.onmessage = null;
+    this.onmessageerror = null;
   }
   /**
-   * Load ServiceWorker using worker pool (multi-threaded mode or dev mode)
+   * Register a ServiceWorker script
+   * Spawns worker threads and runs lifecycle
    */
-  async #loadServiceWorkerWithPool(entrypoint, _options, workerCount) {
-    const entryPath = Path.resolve(this.#options.cwd, entrypoint);
-    let config = this.#options.config;
+  async register(scriptURL, options) {
+    const urlStr = typeof scriptURL === "string" ? scriptURL : scriptURL.toString();
+    const scope = options?.scope ?? "/";
+    let entryPath;
+    if (urlStr.startsWith("file://")) {
+      entryPath = new URL(urlStr).pathname;
+    } else {
+      entryPath = Path.resolve(this.#platform.options.cwd, urlStr);
+    }
+    let config = this.#platform.options.config;
     const configPath = Path.join(Path.dirname(entryPath), "config.js");
     try {
       const configModule = await import(configPath);
       config = configModule.config ?? config;
-    } catch (err) {
-      logger.debug`Using platform config (no config.js): ${err}`;
+    } catch (error) {
+      logger.debug`Using platform config (no config.js found): ${error}`;
     }
-    if (!this.#cacheStorage) {
+    if (!this.#cacheStorage && config?.caches) {
       this.#cacheStorage = new CustomCacheStorage(
-        createCacheFactory({
-          configs: config?.caches ?? {}
-        })
+        createCacheFactory({ configs: config.caches })
       );
     }
-    if (this.#singleThreadedRuntime) {
-      await this.#singleThreadedRuntime.terminate();
-      this.#singleThreadedRuntime = void 0;
+    if (this.#pool) {
+      await this.#pool.terminate();
     }
-    if (this.#workerPool) {
-      await this.#workerPool.terminate();
-    }
-    logger.info("Creating ServiceWorker pool", {
-      entryPath,
-      workerCount
-    });
-    this.#workerPool = new ServiceWorkerPool(
+    this.#pool = new ServiceWorkerPool(
       {
-        workerCount,
-        requestTimeout: 3e4,
-        cwd: this.#options.cwd
+        workerCount: this.#platform.options.workers,
+        createWorker: (entrypoint) => this.#platform.createWorker(entrypoint)
       },
       entryPath,
       this.#cacheStorage
     );
-    await this.#workerPool.init();
-    const workerPool = this.#workerPool;
-    const platform = this;
-    const instance = {
-      runtime: workerPool,
-      handleRequest: async (request) => {
-        if (!platform.#workerPool) {
-          throw new Error("ServiceWorkerPool not initialized");
-        }
-        return platform.#workerPool.handleRequest(request);
-      },
-      install: async () => {
-        logger.info("ServiceWorker installed", {
-          method: "worker_threads"
-        });
-      },
-      activate: async () => {
-        logger.info("ServiceWorker activated", {
-          method: "worker_threads"
-        });
-      },
-      get ready() {
-        return workerPool?.ready ?? false;
-      },
-      dispose: async () => {
-        if (platform.#workerPool) {
-          await platform.#workerPool.terminate();
-          platform.#workerPool = void 0;
-        }
-        logger.info("ServiceWorker disposed", {});
-      }
-    };
-    logger.info("ServiceWorker loaded", {
-      features: ["worker_threads", "coordinated_caches"]
-    });
-    return instance;
+    await this.#pool.init();
+    this.#registration = new ShovelServiceWorkerRegistration(scope, urlStr);
+    this.#registration[kServiceWorker]._setState("activated");
+    this.#readyResolve?.(this.#registration);
+    return this.#registration;
   }
   /**
-   * Create cache storage using config from shovel.json
-   * Used for testing - production uses the generated config module
-   * Merges with runtime defaults (actual class references) for fallback behavior
+   * Get registration for scope
    */
-  async createCaches() {
-    const runtimeDefaults = {
-      default: { impl: MemoryCache }
-    };
-    const userCaches = this.#options.config?.caches ?? {};
-    const configs = {};
-    const allNames = /* @__PURE__ */ new Set([
-      ...Object.keys(runtimeDefaults),
-      ...Object.keys(userCaches)
-    ]);
-    for (const name of allNames) {
-      configs[name] = { ...runtimeDefaults[name], ...userCaches[name] };
+  async getRegistration(scope) {
+    if (scope === void 0 || scope === "/" || scope === this.#registration?.scope) {
+      return this.#registration;
     }
-    return new CustomCacheStorage(createCacheFactory({ configs }));
+    return void 0;
+  }
+  /**
+   * Get all registrations
+   */
+  async getRegistrations() {
+    return this.#registration ? [this.#registration] : [];
   }
   /**
-   * Create directory storage using config from shovel.json
-   * Used for testing - production uses the generated config module
-   * Merges with runtime defaults (actual class references) for fallback behavior
+   * Start receiving messages (no-op in server context)
    */
-  async createDirectories() {
-    const runtimeDefaults = {
-      server: { impl: NodeFSDirectory, path: this.#options.cwd },
-      public: { impl: NodeFSDirectory, path: this.#options.cwd },
-      tmp: { impl: NodeFSDirectory, path: tmpdir() }
+  startMessages() {
+  }
+  /**
+   * Ready promise - resolves when a registration is active
+   */
+  get ready() {
+    return this.#readyPromise;
+  }
+  /**
+   * Internal: Get worker pool for request handling
+   */
+  get pool() {
+    return this.#pool;
+  }
+  /**
+   * Internal: Terminate workers and dispose cache storage
+   */
+  async terminate() {
+    await this.#pool?.terminate();
+    this.#pool = void 0;
+    await this.#cacheStorage?.dispose();
+    this.#cacheStorage = void 0;
+  }
+  /**
+   * Internal: Reload workers (for hot reload)
+   */
+  async reloadWorkers(entrypoint) {
+    await this.#pool?.reloadWorkers(entrypoint);
+  }
+};
+var NodePlatform = class {
+  name;
+  serviceWorker;
+  #options;
+  #server;
+  constructor(options = {}) {
+    this.name = "node";
+    const cwd = options.cwd || process.cwd();
+    this.#options = {
+      port: options.port ?? 3e3,
+      host: options.host ?? "localhost",
+      workers: options.workers ?? 1,
+      cwd,
+      config: options.config
     };
-    const userDirs = this.#options.config?.directories ?? {};
-    const configs = {};
-    const allNames = /* @__PURE__ */ new Set([
-      ...Object.keys(runtimeDefaults),
-      ...Object.keys(userDirs)
-    ]);
-    for (const name of allNames) {
-      configs[name] = { ...runtimeDefaults[name], ...userDirs[name] };
-    }
-    return new CustomDirectoryStorage(createDirectoryFactory(configs));
+    this.serviceWorker = new NodeServiceWorkerContainer(this);
   }
   /**
-   * Create logger storage using config from shovel.json
+   * Create a worker instance for the pool
+   * Can be overridden for testing
    */
-  async createLoggers() {
-    return new CustomLoggerStorage((categories) => getLogger(categories));
+  async createWorker(entrypoint) {
+    const { Worker: NodeWebWorker } = await import("@b9g/node-webworker");
+    return new NodeWebWorker(entrypoint);
   }
   /**
-   * Create database storage from declarative config in shovel.json
+   * Start the HTTP server, routing requests to ServiceWorker
    */
-  createDatabases(configOverride) {
-    const config = configOverride ?? this.#options.config;
-    if (config?.databases && Object.keys(config.databases).length > 0) {
-      const factory = createDatabaseFactory(config.databases);
-      return new CustomDatabaseStorage(factory);
+  async listen() {
+    const pool = this.serviceWorker.pool;
+    if (!pool) {
+      throw new Error(
+        "No ServiceWorker registered. Call serviceWorker.register() first."
+      );
     }
-    return void 0;
+    this.#server = this.createServer((request) => pool.handleRequest(request));
+    await this.#server.listen();
+    return this.#server;
+  }
+  /**
+   * Close the server and terminate workers
+   */
+  async close() {
+    await this.#server?.close();
+    await this.serviceWorker.terminate();
+  }
+  /**
+   * Get options for testing
+   */
+  get options() {
+    return this.#options;
   }
   /**
-   * SUPPORTING UTILITY - Create HTTP server for Node.js
+   * Create HTTP server for Node.js
    */
   createServer(handler, options = {}) {
     const port = options.port ?? this.#options.port;
@@ -531,8 +221,15 @@ var NodePlatform = class extends BasePlatform {
         }
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
-        logger.error("Request error: {error}", { error: err });
         const httpError = isHTTPError(error) ? error : new InternalServerError(err.message, { cause: err });
+        if (httpError.status >= 500) {
+          logger.error("Request error: {error}", { error: err });
+        } else {
+          logger.warn("Request error: {status} {error}", {
+            status: httpError.status,
+            error: err
+          });
+        }
         const isDev = import.meta.env?.MODE !== "production";
         const response = httpError.toResponse(isDev);
         res.statusCode = response.status;
@@ -584,31 +281,89 @@ var NodePlatform = class extends BasePlatform {
   }
   /**
    * Reload workers for hot reloading (called by CLI)
+   * @deprecated Use serviceWorker.reloadWorkers() instead
    * @param entrypoint - Path to the new entrypoint (hashed filename)
    */
   async reloadWorkers(entrypoint) {
-    if (this.#workerPool) {
-      await this.#workerPool.reloadWorkers(entrypoint);
-    } else if (this.#singleThreadedRuntime) {
-      await this.#singleThreadedRuntime.load(entrypoint);
-    }
+    await this.serviceWorker.reloadWorkers(entrypoint);
   }
   /**
-   * Get virtual entry wrapper for Node.js
+   * Get entry points for bundling.
    *
-   * @param entryPath - Absolute path to user's entrypoint file
-   * @param options - Entry wrapper options
-   * @param options.type - "production" (default) or "worker"
+   * Development mode:
+   * - worker.js: Single worker with message loop (develop command acts as supervisor)
    *
-   * Returns:
-   * - "production": Server entry that loads ServiceWorkerPool
-   * - "worker": Worker entry that sets up runtime and message loop
+   * Production mode:
+   * - index.js: Supervisor that spawns workers and owns the HTTP server
+   * - worker.js: Worker that handles requests via message loop
    */
-  getEntryWrapper(entryPath, options) {
-    if (options?.type === "worker") {
-      return workerEntryTemplate.replace("__USER_ENTRY__", entryPath);
+  getEntryPoints(userEntryPath, mode) {
+    const workerCode = `// Node.js Worker
+import {parentPort} from "node:worker_threads";
+import {configureLogging, initWorkerRuntime, runLifecycle, startWorkerMessageLoop} from "@b9g/platform/runtime";
+import {config} from "shovel:config";
+
+await configureLogging(config.logging);
+
+// Initialize worker runtime (installs ServiceWorker globals)
+const {registration, databases} = await initWorkerRuntime({config});
+
+// Import user code (registers event handlers)
+await import("${userEntryPath}");
+
+// Run ServiceWorker lifecycle (stage from config.lifecycle if present)
+await runLifecycle(registration, config.lifecycle?.stage);
+
+// Start message loop for request handling, or signal ready and exit in lifecycle-only mode
+if (config.lifecycle) {
+	parentPort?.postMessage({type: "ready"});
+	// Clean shutdown after lifecycle
+	if (databases) await databases.closeAll();
+	process.exit(0);
+} else {
+	startWorkerMessageLoop({registration, databases});
+}
+`;
+    if (mode === "development") {
+      return { worker: workerCode };
     }
-    return entryTemplate;
+    const supervisorCode = `// Node.js Production Supervisor
+import {Worker} from "@b9g/node-webworker";
+import {getLogger} from "@logtape/logtape";
+import {configureLogging} from "@b9g/platform/runtime";
+import NodePlatform from "@b9g/platform-node";
+import {config} from "shovel:config";
+
+await configureLogging(config.logging);
+const logger = getLogger(["shovel", "platform"]);
+
+logger.info("Starting production server", {port: config.port, workers: config.workers});
+
+// Initialize platform and register ServiceWorker
+// Override createWorker to use the imported Worker class (avoids require() issues with ESM)
+const platform = new NodePlatform({port: config.port, host: config.host, workers: config.workers});
+platform.createWorker = (entrypoint) => new Worker(entrypoint);
+await platform.serviceWorker.register(new URL("./worker.js", import.meta.url).href);
+await platform.serviceWorker.ready;
+
+// Start HTTP server
+await platform.listen();
+
+logger.info("Server started", {port: config.port, host: config.host, workers: config.workers});
+
+// Graceful shutdown
+const handleShutdown = async () => {
+	logger.info("Shutting down");
+	await platform.close();
+	process.exit(0);
+};
+process.on("SIGINT", handleShutdown);
+process.on("SIGTERM", handleShutdown);
+`;
+    return {
+      supervisor: supervisorCode,
+      worker: workerCode
+    };
   }
   /**
    * Get Node.js-specific esbuild configuration
@@ -663,22 +418,8 @@ var NodePlatform = class extends BasePlatform {
    * Dispose of platform resources
    */
   async dispose() {
-    if (this.#singleThreadedRuntime) {
-      await this.#singleThreadedRuntime.terminate();
-      this.#singleThreadedRuntime = void 0;
-    }
-    if (this.#workerPool) {
-      await this.#workerPool.terminate();
-      this.#workerPool = void 0;
-    }
-    if (this.#cacheStorage) {
-      await this.#cacheStorage.dispose();
-      this.#cacheStorage = void 0;
-    }
-    if (this.#databaseStorage) {
-      await this.#databaseStorage.closeAll();
-      this.#databaseStorage = void 0;
-    }
+    await this.close();
+    await this.serviceWorker.terminate();
   }
   // =========================================================================
   // Config Expression Method Overrides
@@ -692,7 +433,8 @@ var NodePlatform = class extends BasePlatform {
 };
 var src_default = NodePlatform;
 export {
-  MemoryCache2 as DefaultCache,
+  MemoryCache as DefaultCache,
   NodePlatform,
+  NodeServiceWorkerContainer,
   src_default as default
 };

package/src/platform.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Node.js Platform Module
+ *
+ * Build-time and dev-time functions for Node.js.
+ * Runtime functions are in ./runtime.ts
+ */
+import type { EntryPoints, ESBuildConfig, PlatformDefaults, DevServerOptions, DevServer } from "@b9g/platform/module";
+export declare const name = "node";
+/**
+ * Get entry points for bundling.
+ *
+ * Development mode:
+ * - worker.js: Single worker with message loop (develop command acts as supervisor)
+ *
+ * Production mode:
+ * - supervisor.js: Spawns workers and owns the HTTP server
+ * - worker.js: Handles requests via message loop
+ */
+export declare function getEntryPoints(userEntryPath: string, mode: "development" | "production"): EntryPoints;
+/**
+ * Get ESBuild configuration for Node.js.
+ *
+ * Note: Node.js doesn't support import.meta.env natively, so we alias it
+ * to process.env for compatibility with code that uses Vite-style env access.
+ */
+export declare function getESBuildConfig(): ESBuildConfig;
+/**
+ * Get platform defaults for config generation.
+ *
+ * Provides default directories (server, public, tmp) that work
+ * out of the box for Node.js deployments.
+ */
+export declare function getDefaults(): PlatformDefaults;
+/**
+ * Create a dev server using ServiceWorkerPool.
+ *
+ * Dynamically imports the platform class to keep heavy dependencies
+ * out of production bundles.
+ */
+export declare function createDevServer(options: DevServerOptions): Promise<DevServer>;

package/src/platform.js

@@ -0,0 +1,146 @@
+/// <reference types="./platform.d.ts" />
+// src/platform.ts
+import { builtinModules } from "node:module";
+import { getLogger } from "@logtape/logtape";
+var logger = getLogger(["shovel", "platform"]);
+var name = "node";
+function getEntryPoints(userEntryPath, mode) {
+  const safePath = JSON.stringify(userEntryPath);
+  const workerCode = `// Node.js Worker
+import {parentPort} from "node:worker_threads";
+import {configureLogging, initWorkerRuntime, runLifecycle, startWorkerMessageLoop} from "@b9g/platform/runtime";
+import {config} from "shovel:config";
+
+await configureLogging(config.logging);
+
+// Initialize worker runtime (installs ServiceWorker globals)
+const {registration, databases} = await initWorkerRuntime({config});
+
+// Import user code (registers event handlers)
+await import(${safePath});
+
+// Run ServiceWorker lifecycle (stage from config.lifecycle if present)
+await runLifecycle(registration, config.lifecycle?.stage);
+
+// Start message loop for request handling, or signal ready and exit in lifecycle-only mode
+if (config.lifecycle) {
+	parentPort?.postMessage({type: "ready"});
+	// Clean shutdown after lifecycle
+	if (databases) await databases.closeAll();
+	process.exit(0);
+} else {
+	startWorkerMessageLoop({registration, databases});
+}
+`;
+  if (mode === "development") {
+    return { worker: workerCode };
+  }
+  const supervisorCode = `// Node.js Production Supervisor
+import {Worker} from "@b9g/node-webworker";
+import {getLogger} from "@logtape/logtape";
+import {configureLogging} from "@b9g/platform/runtime";
+import NodePlatform from "@b9g/platform-node";
+import {config} from "shovel:config";
+
+await configureLogging(config.logging);
+const logger = getLogger(["shovel", "platform"]);
+
+logger.info("Starting production server", {port: config.port, workers: config.workers});
+
+// Initialize platform and register ServiceWorker
+// Override createWorker to use the imported Worker class (avoids require() issues with ESM)
+const platform = new NodePlatform({port: config.port, host: config.host, workers: config.workers});
+platform.createWorker = (entrypoint) => new Worker(entrypoint);
+await platform.serviceWorker.register(new URL("./worker.js", import.meta.url).href);
+await platform.serviceWorker.ready;
+
+// Start HTTP server
+await platform.listen();
+
+logger.info("Server started", {port: config.port, host: config.host, workers: config.workers});
+
+// Graceful shutdown
+const handleShutdown = async () => {
+	logger.info("Shutting down");
+	await platform.close();
+	process.exit(0);
+};
+process.on("SIGINT", handleShutdown);
+process.on("SIGTERM", handleShutdown);
+`;
+  return {
+    supervisor: supervisorCode,
+    worker: workerCode
+  };
+}
+function getESBuildConfig() {
+  return {
+    platform: "node",
+    external: ["node:*", ...builtinModules],
+    define: {
+      // Node.js doesn't support import.meta.env, alias to process.env
+      "import.meta.env": "process.env"
+    }
+  };
+}
+function getDefaults() {
+  return {
+    caches: {
+      default: {
+        module: "@b9g/cache/memory",
+        export: "MemoryCache"
+      }
+    },
+    directories: {
+      server: {
+        module: "@b9g/filesystem/node-fs",
+        export: "NodeFSDirectory",
+        path: "[outdir]/server"
+      },
+      public: {
+        module: "@b9g/filesystem/node-fs",
+        export: "NodeFSDirectory",
+        path: "[outdir]/public"
+      },
+      tmp: {
+        module: "@b9g/filesystem/node-fs",
+        export: "NodeFSDirectory",
+        path: "[tmpdir]"
+      }
+    }
+  };
+}
+async function createDevServer(options) {
+  const { port, host, workerPath, workers = 1 } = options;
+  logger.info("Starting Node.js dev server", { workerPath, workers });
+  const { default: NodePlatform } = await import("./index.js");
+  const platform = new NodePlatform({
+    port,
+    host,
+    workers
+  });
+  await platform.serviceWorker.register(workerPath);
+  await platform.serviceWorker.ready;
+  await platform.listen();
+  logger.info("Node.js dev server ready");
+  const url = `http://${host}:${port}`;
+  return {
+    url,
+    async reload(newWorkerPath) {
+      logger.info("Reloading workers", { workerPath: newWorkerPath });
+      await platform.serviceWorker.reloadWorkers(newWorkerPath);
+      logger.info("Workers reloaded");
+    },
+    async close() {
+      logger.info("Stopping Node.js dev server");
+      await platform.dispose();
+    }
+  };
+}
+export {
+  createDevServer,
+  getDefaults,
+  getESBuildConfig,
+  getEntryPoints,
+  name
+};