@lithia-js/core 1.0.0-canary.2 → 1.0.0-canary.21

package/dist/workers/app-worker.mjs

@@ -0,0 +1,1907 @@
+import { parentPort, workerData, isMainThread } from 'worker_threads';
+import { logger, red, yellow, green } from '@lithia-js/utils';
+import { randomUUID, createHash } from 'crypto';
+import { AsyncLocalStorage } from 'async_hooks';
+import { createServer as createServer$1 } from 'http';
+import { createServer } from 'https';
+import busboy from 'busboy';
+import { parse, serialize } from 'cookie';
+import { access, readFile, constants, stat } from 'fs/promises';
+import { pathToFileURL } from 'url';
+import { isAsyncFunction } from 'util/types';
+import path, { join, normalize, extname } from 'path';
+import { statSync, createReadStream } from 'fs';
+import { Server } from 'socket.io';
+import cron from 'node-cron';
+
+// src/runtime/workers/app-worker.ts
+
+// src/errors/base.ts
+var LithiaError = class extends Error {
+  isLithiaError = true;
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var LithiaClientError = class extends LithiaError {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+  timestamp = /* @__PURE__ */ new Date();
+};
+
+// src/errors/internal/loader.ts
+var NoDefaultExportError = class extends LithiaError {
+  constructor(filePath) {
+    super(`Module at '${filePath}' is missing a default export.`);
+  }
+};
+var NoAsyncDefaultExportError = class extends LithiaError {
+  constructor(filePath) {
+    super(`Default export at '${filePath}' must be an async function.`);
+  }
+};
+
+// src/context/lithia-context.ts
+var LITHIA_CONTEXT_KEY = /* @__PURE__ */ Symbol.for("lithia.base_context.v1");
+function getGlobalLithiaStore() {
+  const globalAny = globalThis;
+  if (!globalAny[LITHIA_CONTEXT_KEY]) {
+    globalAny[LITHIA_CONTEXT_KEY] = new AsyncLocalStorage();
+  }
+  return globalAny[LITHIA_CONTEXT_KEY];
+}
+var lithiaContextStore = getGlobalLithiaStore();
+function runInLithiaContext(context, fn) {
+  return lithiaContextStore.run(context, fn);
+}
+var ROUTE_CONTEXT_KEY = /* @__PURE__ */ Symbol.for("lithia.route_context.v1");
+function getGlobalRouteStore() {
+  const globalAny = globalThis;
+  if (!globalAny[ROUTE_CONTEXT_KEY]) {
+    globalAny[ROUTE_CONTEXT_KEY] = new AsyncLocalStorage();
+  }
+  return globalAny[ROUTE_CONTEXT_KEY];
+}
+var routeContextStore = getGlobalRouteStore();
+
+// src/errors/app/client.ts
+var BadRequestError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 400, d);
+  }
+};
+var RouteNotFoundError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 404, d);
+  }
+};
+
+// src/errors/app/server.ts
+var InternalServerError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 500, d);
+  }
+};
+
+// src/transport/http/request.ts
+var LithiaRequest = class {
+  /**
+   * Creates a request wrapper for the current HTTP transaction.
+   *
+   * The constructor captures headers, reconstructs a best-effort absolute URL,
+   * normalizes the HTTP method to uppercase, and initializes parsed query and
+   * route-param containers for later middleware and handler use.
+   *
+   * @param {IncomingMessage} req - Raw Node.js request object received by the
+   * HTTP server.
+   * @param {{ maxBodySize?: number }} opts - Per-request parsing options used
+   * when consuming the request body stream.
+   */
+  constructor(req, opts) {
+    this.req = req;
+    this.opts = opts;
+    this.headers = req.headers;
+    const isSecure = this.isSecure();
+    const host = this.headers.host || req.headers.host || "unknown";
+    const fullUrl = `${isSecure ? "https" : "http"}://${host}${req.url || "/"}`;
+    const url = new URL(fullUrl);
+    this.pathname = url.pathname;
+    this.method = (req.method || "GET").toUpperCase();
+    this.query = parseQueryToObject(url.searchParams);
+    this.params = {};
+  }
+  headers;
+  method;
+  pathname;
+  query;
+  params;
+  storage = /* @__PURE__ */ new Map();
+  _bodyCache = null;
+  _filesCache = null;
+  _cookies = null;
+  /**
+   * Returns the best-effort client IP address for the current request.
+   *
+   * The lookup prefers proxy-forwarded headers before falling back to the raw
+   * socket address, which makes the result suitable for deployments behind
+   * reverse proxies that preserve `x-forwarded-for` or `x-real-ip`.
+   *
+   * @returns {string} The resolved client IP address, or `"unknown"` when no
+   * address can be derived.
+   */
+  ip() {
+    return this.headers["x-forwarded-for"]?.split(",")[0]?.trim() || this.headers["x-real-ip"] || this.req.socket?.remoteAddress || "unknown";
+  }
+  /**
+   * Returns the current request user-agent string.
+   *
+   * @returns {string} The raw `user-agent` header value, or an empty string
+   * when the header is missing.
+   */
+  userAgent() {
+    return this.headers["user-agent"] || "";
+  }
+  /**
+   * Returns whether the current request is using HTTPS.
+   *
+   * The check prefers `x-forwarded-proto` for proxy-aware deployments and then
+   * falls back to the encrypted state of the underlying socket.
+   *
+   * @returns {boolean} `true` when the request should be treated as HTTPS.
+   */
+  isSecure() {
+    return this.headers["x-forwarded-proto"] === "https" || this.req.socket?.encrypted === true;
+  }
+  /**
+   * Returns the request host header.
+   *
+   * @returns {string} The current host header value, or `"unknown"` when it is
+   * not available.
+   */
+  host() {
+    return this.headers.host || "unknown";
+  }
+  /**
+   * Returns the absolute request URL reconstructed from the current request.
+   *
+   * This helper rebuilds the URL from the current security state, host header,
+   * and parsed pathname. It does not append the original query string.
+   *
+   * @returns {string} Absolute URL for the current request pathname.
+   */
+  url() {
+    return `${this.isSecure() ? "https" : "http"}://${this.host()}${this.pathname}`;
+  }
+  /**
+   * Parses and returns the request body.
+   *
+   * JSON and plain text bodies are supported automatically. Multipart requests
+   * populate both `body()` and `files()` through a shared parsing pass. The
+   * parsed value is cached after the first read so later consumers do not touch
+   * the underlying stream again.
+   *
+   * Requests whose method is not one of `POST`, `PUT`, `PATCH`, or `DELETE`
+   * resolve to an empty object without reading the stream.
+   *
+   * @returns {Promise<T>} Parsed request body, multipart field map, raw text, or
+   * an empty object for methods that do not consume a body by default.
+   * @throws {BadRequestError} Thrown when the declared or streamed body size
+   * exceeds `maxBodySize`, or when JSON parsing fails.
+   */
+  async body() {
+    const methodsWithBody = ["POST", "PUT", "PATCH", "DELETE"];
+    if (!methodsWithBody.includes(this.method)) {
+      return {};
+    }
+    if (this._bodyCache !== null) return this._bodyCache;
+    const contentType = this.headers["content-type"] || "";
+    if (contentType.includes("multipart/form-data")) {
+      await this.parseMultipart();
+      return this._bodyCache;
+    }
+    const contentLength = parseInt(
+      this.headers["content-length"] || "0",
+      10
+    );
+    const maxBodySize = this.opts.maxBodySize || 1024 * 1024;
+    if (contentLength > maxBodySize) {
+      throw new BadRequestError("Request body too large.");
+    }
+    const body = await new Promise((resolve, reject) => {
+      const chunks = [];
+      let currentSize = 0;
+      this.req.on("data", (chunk) => {
+        currentSize += chunk.length;
+        if (currentSize > maxBodySize) {
+          reject(new BadRequestError("Request body too large."));
+        }
+        chunks.push(chunk);
+      });
+      this.req.on("end", () => {
+        if (chunks.length === 0) return resolve({});
+        const rawBody = Buffer.concat(chunks).toString("utf-8");
+        try {
+          if (contentType.includes("application/json")) {
+            resolve(JSON.parse(rawBody));
+          } else {
+            resolve(rawBody);
+          }
+        } catch {
+          reject(new BadRequestError("Invalid request body format."));
+        }
+      });
+      this.req.on("error", (err) => reject(err));
+    });
+    this._bodyCache = body;
+    this.storage.set("body", body);
+    return body;
+  }
+  /**
+   * Returns uploaded files for multipart/form-data requests.
+   *
+   * `files()` shares the same multipart parsing pass used by `body()`. The
+   * first call buffers every uploaded file into memory and caches both the
+   * parsed field object and file array for later access.
+   *
+   * @returns {Promise<UploadedFile[]>} Buffered multipart files, or an empty
+   * array when the request is not multipart.
+   */
+  async files() {
+    const contentType = this.headers["content-type"] || "";
+    if (!contentType.includes("multipart/form-data")) return [];
+    if (this._filesCache !== null) return this._filesCache;
+    await this.parseMultipart();
+    return this._filesCache || [];
+  }
+  /**
+   * Overrides the cached body value for the current request context.
+   *
+   * This mutates only the wrapper cache and the internal storage map. It does
+   * not modify the underlying Node.js request stream.
+   *
+   * @param {unknown} value - Replacement body value to expose through `body()`
+   * and internal request storage.
+   */
+  setBody(value) {
+    this._bodyCache = value;
+    this.storage.set("body", value);
+  }
+  /**
+   * Returns all parsed cookies from the request.
+   *
+   * Cookies are parsed lazily on first access and cached for the remainder of
+   * the request lifecycle.
+   *
+   * @returns {Cookies} Parsed cookie map for the current request.
+   */
+  cookies() {
+    if (this._cookies === null) {
+      const cookieHeader = this.headers.cookie;
+      this._cookies = cookieHeader ? parse(cookieHeader) : {};
+    }
+    return this._cookies;
+  }
+  /**
+   * Returns a single cookie value by name.
+   *
+   * @param {string} name - Cookie name to read from the parsed cookie map.
+   * @returns {string | undefined} The cookie value when present.
+   */
+  cookie(name) {
+    return this.cookies()[name];
+  }
+  /**
+   * Returns a value stored in the per-request internal storage map.
+   *
+   * This storage is local to the current request wrapper and can be used by
+   * middleware and handlers to exchange derived values without mutating the
+   * typed request surface.
+   *
+   * @param {string} key - Storage key associated with the requested value.
+   * @returns {T | undefined} Stored value for the key, if one exists.
+   */
+  get(key) {
+    return this.storage.get(key);
+  }
+  /**
+   * Stores a value in the per-request internal storage map.
+   *
+   * @param {string} key - Storage key to create or overwrite.
+   * @param {unknown} value - Arbitrary value to retain for the lifetime of the
+   * current request wrapper.
+   */
+  set(key, value) {
+    this.storage.set(key, value);
+  }
+  /**
+   * Parses a multipart/form-data request into cached fields and file buffers.
+   *
+   * The request stream is piped into Busboy exactly once. Field values are
+   * collected into a plain object, file contents are buffered fully in memory,
+   * and both results are stored in the request cache and internal storage map.
+   *
+   * @returns {Promise<void>} Resolves after Busboy finishes consuming the
+   * multipart stream and caches the parsed payload.
+   */
+  async parseMultipart() {
+    if (this._bodyCache !== null && this._filesCache !== null) return;
+    return new Promise((resolve, reject) => {
+      const bb = busboy({ headers: this.headers });
+      const fields = {};
+      const files = [];
+      bb.on("file", (name, file, info) => {
+        const chunks = [];
+        file.on("data", (data) => chunks.push(data));
+        file.on("end", () => {
+          files.push({
+            fieldname: name,
+            buffer: Buffer.concat(chunks),
+            ...info
+          });
+        });
+      });
+      bb.on("field", (name, value) => {
+        fields[name] = value;
+      });
+      bb.on("finish", () => {
+        this._bodyCache = fields;
+        this._filesCache = files;
+        this.storage.set("body", fields);
+        this.storage.set("files", files);
+        resolve();
+      });
+      bb.on("error", reject);
+      this.req.pipe(bb);
+    });
+  }
+};
+function parseQueryToObject(searchParams) {
+  const query = {};
+  for (const [key, value] of searchParams.entries()) {
+    query[key] = value;
+  }
+  return query;
+}
+async function loadModule(filePath) {
+  const exists = await access(filePath, constants.F_OK).then(() => true).catch(() => false);
+  if (!exists) {
+    throw new LithiaError(
+      `The module at '${filePath}' could not be found or is not accessible.`
+    );
+  }
+  let mod;
+  try {
+    mod = await import(pathToFileURL(filePath).href);
+  } catch (err) {
+    throw new LithiaError(
+      `Failed to import module at '${filePath}': ${err.message}`
+    );
+  }
+  if (!mod || !mod.default) {
+    throw new NoDefaultExportError(filePath);
+  }
+  const isFunction = typeof mod.default === "function";
+  const isAsync = isAsyncFunction(mod.default);
+  if (!isFunction || !isAsync) {
+    throw new NoAsyncDefaultExportError(filePath);
+  }
+  return mod;
+}
+
+// src/shared/pipeline.ts
+async function executePipeline(steps, handler) {
+  let index = -1;
+  const dispatch = async (stepIndex) => {
+    if (stepIndex <= index) return;
+    index = stepIndex;
+    if (stepIndex === steps.length) {
+      return handler();
+    }
+    const step = steps[stepIndex];
+    if (step) {
+      await step(() => dispatch(stepIndex + 1));
+    }
+  };
+  await dispatch(0);
+}
+
+// src/transport/http/cors-policy.ts
+function applyCorsPolicy(config, req, res) {
+  const { cors } = config.http;
+  if (!cors?.origin?.length) return false;
+  const requestOrigin = req.headers.origin;
+  if (!requestOrigin) return false;
+  const isOriginAllowed = cors.origin.includes("*") || cors.origin.some((allowed) => allowed === requestOrigin);
+  if (!isOriginAllowed) return false;
+  const allowedOrigin = cors.origin.includes("*") ? cors.credentials ? requestOrigin : "*" : requestOrigin;
+  res.setHeader("Access-Control-Allow-Origin", allowedOrigin);
+  res.setHeader("Vary", "Origin");
+  if (cors.credentials) {
+    res.setHeader("Access-Control-Allow-Credentials", "true");
+  }
+  if (cors.exposedHeaders?.length) {
+    res.setHeader(
+      "Access-Control-Expose-Headers",
+      cors.exposedHeaders.join(", ")
+    );
+  }
+  if (req.method !== "OPTIONS") return false;
+  if (cors.methods?.length) {
+    res.setHeader("Access-Control-Allow-Methods", cors.methods.join(", "));
+  }
+  if (cors.allowedHeaders?.length) {
+    res.setHeader(
+      "Access-Control-Allow-Headers",
+      cors.allowedHeaders.join(", ")
+    );
+  }
+  if (cors.maxAge != null) {
+    res.setHeader("Access-Control-Max-Age", String(cors.maxAge));
+  }
+  res.status(204).end();
+  return true;
+}
+var DOCS_FILE = path.join("_lithia", "scalar.html");
+var SPEC_FILE = path.join("_lithia", "openapi.json");
+async function serveOpenAPIAsset(config, req, res) {
+  if (!config.openapi?.enabled) return false;
+  if (req.method !== "GET" && req.method !== "HEAD") return false;
+  const docsPath = normalizeOpenAPIPath(config.openapi.docsPath || "/docs");
+  const specPath = normalizeOpenAPIPath(
+    config.openapi.specPath || "/openapi.json"
+  );
+  const pathname = normalizeOpenAPIPath(req.pathname);
+  if (pathname === docsPath) {
+    const html = await readOpenAPIArtifact(config.outDir, DOCS_FILE);
+    if (!html) return false;
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.send(req.method === "HEAD" ? void 0 : html);
+    return true;
+  }
+  if (pathname === specPath) {
+    const spec = await readOpenAPIArtifact(config.outDir, SPEC_FILE);
+    if (!spec) return false;
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.send(req.method === "HEAD" ? void 0 : spec);
+    return true;
+  }
+  return false;
+}
+function normalizeOpenAPIPath(input) {
+  if (!input) return "/";
+  const normalized = input.startsWith("/") ? input : `/${input}`;
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    return normalized.slice(0, -1);
+  }
+  return normalized;
+}
+async function readOpenAPIArtifact(outDir, relativePath) {
+  try {
+    return await readFile(
+      path.join(process.cwd(), outDir, relativePath),
+      "utf-8"
+    );
+  } catch {
+    return null;
+  }
+}
+function produceDigest(err) {
+  const errString = err instanceof Error ? err.stack || err.message : String(err);
+  const hash = createHash("sha256").update(`${errString}${Date.now()}${Math.random()}`).digest("hex");
+  return hash.slice(0, 12);
+}
+
+// src/transport/http/request-error-handler.ts
+function handleRequestError(environment, req, res, err) {
+  if (res._ended) return;
+  const error = err instanceof LithiaClientError ? err : new InternalServerError(err);
+  const isProd = environment === "production";
+  const statusCode = error.statusCode || 500;
+  const digest = produceDigest(err);
+  const message = isProd && statusCode >= 500 ? "Internal Server Error" : error.message;
+  res.status(statusCode).json({
+    error: {
+      statusCode,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      digest,
+      path: req.pathname,
+      method: req.method,
+      details: error.details
+    }
+  });
+  if (statusCode >= 500) {
+    logger.error(`Digest: ${red(digest)}`);
+    logger.info(`Path: ${req.method} ${req.pathname}`);
+    logger.info(err.stack || err);
+  }
+}
+
+// src/transport/http/route-matcher.ts
+var RouteMatcher = class {
+  regexCache = /* @__PURE__ */ new Map();
+  /**
+   * Finds the first discovered route that matches the current request.
+   *
+   * Method-specific routes only match the corresponding request method, while
+   * method-agnostic routes can match any method. Path matching is delegated to
+   * the route manifest regex generated during discovery.
+   *
+   * @param {LithiaRequest} req - Current request wrapper.
+   * @param {Route[]} routes - Discovered route manifests to scan in order.
+   * @returns {Route | undefined} The first matching route manifest, if one
+   * exists.
+   */
+  findRoute(req, routes) {
+    const method = req.method.toLowerCase();
+    return routes.find((route) => {
+      const methodMatches = !route.method || route.method.toLowerCase() === method;
+      if (!methodMatches) return false;
+      const regex = this.getOrCreateRegex(route.regex);
+      return regex.test(req.pathname);
+    });
+  }
+  /**
+   * Synchronizes route-specific context after a route match is selected.
+   *
+   * When a request context store is active, the matched route manifest is
+   * attached to it. Dynamic routes also populate `req.params` by extracting
+   * capture groups from the request pathname.
+   *
+   * @param {Route} route - Matched route manifest.
+   * @param {LithiaRequest} req - Current request wrapper whose params may be
+   * updated.
+   */
+  setupContext(route, req) {
+    const store = routeContextStore.getStore();
+    if (store) {
+      store.route = route;
+    }
+    if (route.dynamic) {
+      req.params = this.extractParams(req.pathname, route);
+    }
+  }
+  /**
+   * Extracts decoded dynamic params from a matched pathname.
+   *
+   * Param names are derived from `route.path` segments such as `:id`, while
+   * values are read from the corresponding regex capture groups in the actual
+   * request pathname.
+   *
+   * @param {string} pathname - Incoming request pathname.
+   * @param {Route} route - Matched route manifest that supplies the paramized
+   * path and regex pattern.
+   * @returns {Params} Decoded param object for the current request.
+   */
+  extractParams(pathname, route) {
+    const regex = this.getOrCreateRegex(route.regex);
+    const match = pathname.match(regex);
+    if (!match) return {};
+    const paramNames = (route.path.match(/:([^/]+)/g) || []).map(
+      (segment) => segment.slice(1)
+    );
+    return paramNames.reduce((params, name, index) => {
+      const value = match[index + 1];
+      params[name] = value ? decodeURIComponent(value) : value;
+      return params;
+    }, {});
+  }
+  /**
+   * Returns a cached regular expression for a route manifest pattern.
+   *
+   * @param {string} pattern - Serialized regex pattern generated during route
+   * discovery.
+   * @returns {RegExp} Cached or newly compiled regular expression.
+   */
+  getOrCreateRegex(pattern) {
+    let regex = this.regexCache.get(pattern);
+    if (!regex) {
+      regex = new RegExp(pattern);
+      this.regexCache.set(pattern, regex);
+    }
+    return regex;
+  }
+};
+async function serveStaticAsset(config, req, res) {
+  const { static: staticConfig, http } = config;
+  if (!staticConfig?.root || req.method !== "GET" && req.method !== "HEAD") {
+    return false;
+  }
+  let relativePath = req.pathname;
+  if (staticConfig.prefix) {
+    if (!relativePath.startsWith(staticConfig.prefix)) return false;
+    relativePath = relativePath.slice(staticConfig.prefix.length);
+  }
+  const safePath = normalize(relativePath).replace(/^(\.\.(\/|\\|$))+/, "");
+  const fullPath = join(staticConfig.root, safePath);
+  try {
+    const stats = await stat(fullPath);
+    if (!stats.isFile()) return false;
+    const ext = extname(fullPath).toLowerCase();
+    const mime = http.mimeTypes?.[ext];
+    if (!mime) return false;
+    res.setHeader("Content-Type", mime);
+    res.send(fullPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/transport/http/request-pipeline.ts
+var LithiaRequestProcessor = class {
+  /**
+   * Creates an HTTP request processor bound to a running Lithia app instance.
+   *
+   * @param {LithiaApp} app - Runtime app state that provides config, manifests,
+   * middleware registries, and environment information for request execution.
+   */
+  constructor(app) {
+    this.app = app;
+  }
+  matcher = new RouteMatcher();
+  /**
+   * Processes a single HTTP request through the Lithia route pipeline.
+   *
+   * The method may terminate early when CORS preflight handling, OpenAPI asset
+   * serving, or static asset serving fully handles the request. Otherwise it
+   * resolves the matching route, prepares request params through the route
+   * matcher, loads the route module, executes global and route-local middleware,
+   * and then runs the route handler.
+   *
+   * If the handler and middleware chain complete without ending the response,
+   * the processor closes the response automatically with `res.end()`.
+   *
+   * @param {LithiaRequest} req - Current request wrapper.
+   * @param {LithiaResponse} res - Current response wrapper.
+   * @returns {Promise<void>} Resolves after the request reaches a terminal
+   * response or the error handler completes.
+   */
+  async process(req, res) {
+    const startTime = performance.now();
+    try {
+      this.setInitialHeaders(res);
+      if (applyCorsPolicy(this.app.config, req, res)) return;
+      if (await serveOpenAPIAsset(this.app.config, req, res)) return;
+      if (await serveStaticAsset(this.app.config, req, res)) return;
+      const route = this.matcher.findRoute(req, this.app.routes);
+      if (!route) {
+        throw new RouteNotFoundError(
+          `The requested resource '${req.pathname}' does not exist on this server.`
+        );
+      }
+      this.matcher.setupContext(route, req);
+      const mod = await loadModule(route.filePath);
+      const pipeline = [
+        ...this.app.globalRouteMiddlewares,
+        ...mod.middlewares || []
+      ];
+      await this.runRoutePipeline(pipeline, req, res, async () => {
+        await mod.default(req, res);
+      });
+      if (!res._ended) res.end();
+    } catch (error) {
+      handleRequestError(this.app.environment, req, res, error);
+    } finally {
+      this.logRequest(req, res, performance.now() - startTime);
+    }
+  }
+  /**
+   * Executes the composed route middleware chain and then the final handler.
+   *
+   * Middleware functions are adapted to the generic shared pipeline runner,
+   * which guarantees in-order execution as long as each middleware calls its
+   * `next()` continuation.
+   *
+   * @param {RouteMiddleware[]} middlewares - Global and route-scoped middleware
+   * stack to execute before the handler.
+   * @param {LithiaRequest} req - Current request wrapper shared across the
+   * entire pipeline.
+   * @param {LithiaResponse} res - Current response wrapper shared across the
+   * entire pipeline.
+   * @param {RouteHandler} handler - Final route handler invoked after all
+   * middleware completes.
+   * @returns {Promise<void>} Resolves after the middleware chain and handler
+   * finish.
+   */
+  async runRoutePipeline(middlewares, req, res, handler) {
+    await executePipeline(
+      middlewares.map(
+        (middleware) => (next) => middleware(req, res, () => next())
+      ),
+      () => handler(req, res)
+    );
+  }
+  /**
+   * Applies framework-default headers before any route logic runs.
+   *
+   * @param {LithiaResponse} res - Response wrapper mutated with initial
+   * framework headers.
+   */
+  setInitialHeaders(res) {
+    res.setHeader("X-Powered-By", "Lithia");
+  }
+  /**
+   * Logs the completed HTTP request when request logging is enabled.
+   *
+   * The status code is color-coded according to its category and the log is
+   * emitted only after the request has reached a terminal state.
+   *
+   * @param {LithiaRequest} req - Request wrapper used for method and pathname
+   * fields.
+   * @param {LithiaResponse} res - Response wrapper used for the final status
+   * code.
+   * @param {number} elapsed - Total request processing time in milliseconds.
+   */
+  logRequest(req, res, elapsed) {
+    if (!this.app.config.logging.requests) return;
+    const status = res.statusCode;
+    const colorFunc = status >= 500 ? red : status >= 400 ? yellow : green;
+    logger.info(
+      `${req.method} ${req.pathname} ${colorFunc(status.toString())} - ${elapsed.toFixed(2)}ms`
+    );
+  }
+};
+var LithiaResponse = class {
+  /**
+   * Creates a response wrapper for the current HTTP transaction.
+   *
+   * The wrapper binds a pass-through `on()` helper to the underlying Node.js
+   * response object so route-adjacent code can subscribe to response events
+   * without holding the raw `ServerResponse`.
+   *
+   * @param {ServerResponse} res - Raw Node.js response object associated with
+   * the current request.
+   */
+  constructor(res) {
+    this.res = res;
+    this.on = this.res.on.bind(this.res);
+  }
+  _ended = false;
+  _cookies = [];
+  on;
+  /**
+   * Returns the current HTTP status code.
+   *
+   * @returns {number} Status code currently assigned to the underlying
+   * response.
+   */
+  get statusCode() {
+    return this.res.statusCode;
+  }
+  /**
+   * Sets the HTTP status code for the response.
+   *
+   * This mutates the underlying response only while it is still active.
+   *
+   * @param {number} status - HTTP status code to assign before the response is
+   * sent.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended or when the
+   * supplied status code falls outside the valid HTTP range.
+   */
+  status(status) {
+    this.ensureActive();
+    if (status < 100 || status > 599) {
+      throw new Error(`Invalid HTTP status code: ${status}`);
+    }
+    this.res.statusCode = status;
+    return this;
+  }
+  /**
+   * Returns the currently assigned response headers.
+   *
+   * @returns {Readonly<OutgoingHttpHeaders>} Snapshot of the headers currently
+   * stored on the underlying response.
+   */
+  headers() {
+    return this.res.getHeaders();
+  }
+  /**
+   * Sets multiple response headers at once.
+   *
+   * @param {OutgoingHttpHeaders} headers - Header entries to assign to the
+   * response before it is sent.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  setHeaders(headers) {
+    this.ensureActive();
+    Object.entries(headers).forEach(([key, value]) => {
+      this.res.setHeader(key, value);
+    });
+    return this;
+  }
+  /**
+   * Sets a single response header.
+   *
+   * @param {string} name - Header name to create or overwrite.
+   * @param {string | number | string[]} value - Header value written to the
+   * underlying response.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  setHeader(name, value) {
+    this.ensureActive();
+    this.res.setHeader(name, value);
+    return this;
+  }
+  /**
+   * Removes a response header.
+   *
+   * @param {string} name - Header name to remove.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  removeHeader(name) {
+    this.ensureActive();
+    this.res.removeHeader(name);
+    return this;
+  }
+  /**
+   * Queues a cookie to be written when the response is sent.
+   *
+   * Cookies are accumulated in memory and serialized only when a terminal
+   * response method flushes headers.
+   *
+   * @param {string} name - Cookie name.
+   * @param {string} value - Cookie value.
+   * @param {CookieOptions} [options={}] - Cookie serialization options.
+   * @returns {this} The current response wrapper for fluent chaining.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  cookie(name, value, options = {}) {
+    this.ensureActive();
+    this._cookies.push({ name, value, options });
+    return this;
+  }
+  /**
+   * Clears a cookie by expiring it immediately.
+   *
+   * @param {string} name - Cookie name to expire.
+   * @param {CookieOptions} [options={}] - Additional cookie attributes that
+   * must match the original cookie scope.
+   * @returns {this} The current response wrapper for fluent chaining.
+   */
+  clearCookie(name, options = {}) {
+    return this.cookie(name, "", { ...options, expires: /* @__PURE__ */ new Date(0) });
+  }
+  /**
+   * Sends a response body using a best-effort content type.
+   *
+   * The method flushes pending cookies before writing, chooses a default
+   * content type when none is set, and treats plain objects as JSON by
+   * delegating to `json()`. Calling `send()` is a terminal operation for the
+   * response lifecycle.
+   *
+   * @param {unknown} [data] - Response payload to send.
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  send(data) {
+    this.applyPendingCookies();
+    this.ensureActive();
+    try {
+      if (data === void 0 || data === null) {
+        this.end();
+        return;
+      }
+      if (Buffer.isBuffer(data)) {
+        if (!this.res.getHeader("Content-Type")) {
+          this.setHeader("Content-Type", "application/octet-stream");
+        }
+        this.res.end(data);
+      } else if (typeof data === "object") {
+        this.json(data);
+        return;
+      } else {
+        if (!this.res.getHeader("Content-Type")) {
+          this.setHeader("Content-Type", "text/plain; charset=utf-8");
+        }
+        this.res.end(String(data));
+      }
+    } finally {
+      this._ended = true;
+    }
+  }
+  /**
+   * Sends a JSON response.
+   *
+   * Pending cookies are flushed before serialization. If JSON serialization
+   * throws, the method logs the failure and falls back to a `500 Internal
+   * Server Error` response body.
+   *
+   * @param {object} obj - Plain object to serialize as JSON.
+   */
+  json(obj) {
+    this.applyPendingCookies();
+    this.ensureActive();
+    try {
+      const body = JSON.stringify(obj);
+      this.res.setHeader("Content-Type", "application/json; charset=utf-8");
+      this.res.end(body);
+    } catch (err) {
+      logger.error("Failed to serialize JSON response:", err);
+      this.res.statusCode = 500;
+      this.res.end("Internal Server Error");
+    } finally {
+      this._ended = true;
+    }
+  }
+  /**
+   * Sends a redirect response.
+   *
+   * This sets the status code, writes the `Location` header, and then ends the
+   * response.
+   *
+   * @param {string} url - Redirect target written to the `Location` header.
+   * @param {number} [status=302] - Redirect status code.
+   */
+  redirect(url, status = 302) {
+    this.status(status).setHeader("Location", url).end();
+  }
+  /**
+   * Ends the response without sending additional data.
+   *
+   * Pending cookies are flushed before the underlying response is closed.
+   *
+   * @throws {Error} Thrown when the response has already ended.
+   */
+  end() {
+    this.applyPendingCookies();
+    this.ensureActive();
+    this.res.end();
+    this._ended = true;
+  }
+  /**
+   * Streams a file to the client.
+   *
+   * The method resolves the final path, verifies that it points to a regular
+   * file, sets `Content-Length`, flushes pending cookies, and pipes the file
+   * stream into the underlying response. Missing files and stream failures fall
+   * back to a `404` JSON error payload.
+   *
+   * @param {string} filePath - File path to stream. When `opts.root` is set, it
+   * is resolved relative to that root.
+   * @param {{ root?: string }} [opts={}] - Optional root directory used to
+   * resolve relative file paths.
+   */
+  sendFile(filePath, opts = {}) {
+    this.ensureActive();
+    try {
+      const fullPath = opts.root ? join(opts.root, filePath) : filePath;
+      const stats = statSync(fullPath);
+      if (!stats.isFile()) throw new Error("Target is not a file");
+      this.setHeader("Content-Length", String(stats.size));
+      const stream = createReadStream(fullPath);
+      this.applyPendingCookies();
+      stream.pipe(this.res);
+      stream.on("error", () => {
+        this.status(404).send({ error: "File not found" });
+      });
+    } catch {
+      this.status(404).send({ error: "File not found" });
+    } finally {
+      this._ended = true;
+    }
+  }
+  /**
+   * Serializes queued cookies into the response headers and clears the queue.
+   *
+   * Existing `Set-Cookie` headers are preserved and extended so multiple
+   * middleware and handler calls can contribute cookies before the response is
+   * finalized.
+   */
+  applyPendingCookies() {
+    if (this._cookies.length === 0) return;
+    const existing = this.res.getHeader("Set-Cookie") || [];
+    const serialized = this._cookies.map(
+      (cookie) => serialize(cookie.name, cookie.value, cookie.options)
+    );
+    this.res.setHeader("Set-Cookie", [...existing, ...serialized]);
+    this._cookies = [];
+  }
+  /**
+   * Ensures the response has not already been finalized.
+   *
+   * @throws {Error} Thrown when a terminal response method has already sent or
+   * ended the response.
+   */
+  ensureActive() {
+    if (this._ended) {
+      throw new Error("Response has already been sent.");
+    }
+  }
+};
+function handleEventError(environment, socket, eventName, err) {
+  const error = err instanceof LithiaClientError ? err : new InternalServerError(
+    "An internal server error occurred during event processing.",
+    err
+  );
+  const isProd = environment === "production";
+  const statusCode = error.statusCode || 500;
+  const digest = produceDigest(err);
+  const message = isProd && statusCode >= 500 ? "Internal Server Error" : error.message;
+  socket.emit("error", {
+    error: {
+      statusCode,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      digest,
+      event: eventName,
+      details: error.details
+    }
+  });
+  if (statusCode >= 500) {
+    logger.error(`Digest: ${red(digest)}`);
+    logger.info(`Event: ${eventName}`);
+    logger.info(`Socket ID: ${socket.id}`);
+    logger.info(err.stack || err);
+  }
+}
+
+// src/transport/socket/event-pipeline.ts
+var LithiaEventProcessor = class {
+  /**
+   * Creates an event processor bound to a running Lithia app instance.
+   *
+   * @param {LithiaApp} app - Runtime app state that provides environment and
+   * global event middleware.
+   */
+  constructor(app) {
+    this.app = app;
+  }
+  /**
+   * Processes a single discovered realtime event.
+   *
+   * @param {Socket} socket - Active socket that triggered the event.
+   * @param {Event} event - Discovered event manifest selected by the socket
+   * transport.
+   * @param {any} [data] - Event payload forwarded from Socket.IO.
+   * @returns {Promise<void>} Resolves after middleware and the event handler
+   * complete, or after the error handler emits a failure payload.
+   */
+  async process(socket, event, data) {
+    try {
+      const module = await loadModule(event.filePath);
+      const pipeline = [
+        ...this.app.globalEventMiddlewares,
+        ...module.middlewares || []
+      ];
+      await executePipeline(
+        pipeline.map(
+          (middleware) => (next) => middleware(socket, () => next())
+        ),
+        () => module.default(socket, data)
+      );
+    } catch (error) {
+      handleEventError(this.app.environment, socket, event.name, error);
+    }
+  }
+};
+var CONTEXT_GLOBAL_KEY = /* @__PURE__ */ Symbol.for("lithia.event_context.v1");
+function getGlobalStore() {
+  const globalAny = globalThis;
+  if (!globalAny[CONTEXT_GLOBAL_KEY]) {
+    globalAny[CONTEXT_GLOBAL_KEY] = new AsyncLocalStorage();
+  }
+  return globalAny[CONTEXT_GLOBAL_KEY];
+}
+var eventContextStore = getGlobalStore();
+
+// src/transport/socket/socket-server.ts
+var LithiaSocketTransport = class {
+  /**
+   * Creates the Socket.IO transport and registers connection listeners.
+   *
+   * The constructor configures Socket.IO CORS from the app's HTTP settings and
+   * immediately wires connection, disconnect, and custom event dispatch into
+   * the Lithia event processor.
+   *
+   * @param {LithiaApp} app - Running app instance that provides config and the
+   * discovered event manifest list.
+   * @param {HttpServer | HttpsServer} httpServer - Underlying HTTP server used
+   * as the Socket.IO transport base.
+   * @param {LithiaEventProcessor} processor - Event processor responsible for
+   * executing event middleware and handlers.
+   */
+  constructor(app, httpServer, processor) {
+    this.app = app;
+    this.processor = processor;
+    const { cors } = this.app.config.http;
+    this.io = new Server(httpServer, {
+      cors: {
+        origin: cors.origin,
+        methods: cors.methods,
+        credentials: cors.credentials
+      }
+    });
+    this.io.on("connection", (socket) => {
+      const eventMap = new Map(
+        this.app.events.map((event) => [event.name, event])
+      );
+      const connectionEvent = eventMap.get("connection");
+      if (connectionEvent) this.dispatch(socket, connectionEvent);
+      socket.on("disconnect", (...args) => {
+        const disconnectEvent = eventMap.get("disconnect");
+        if (disconnectEvent) this.dispatch(socket, disconnectEvent, ...args);
+      });
+      socket.onAny((eventName, ...args) => {
+        const customEvent = this.app.events.find(
+          (event) => event.name === eventName
+        );
+        if (customEvent) this.dispatch(socket, customEvent, ...args);
+      });
+    });
+  }
+  io;
+  /**
+   * Returns the underlying Socket.IO server instance.
+   *
+   * @returns {SocketServer} Active Socket.IO server.
+   */
+  get server() {
+    return this.io;
+  }
+  /**
+   * Closes the Socket.IO transport and disconnects active sockets.
+   *
+   * @returns {Promise<void>} Resolves after Socket.IO finishes shutting down.
+   */
+  async close() {
+    await this.io.close();
+  }
+  /**
+   * Dispatches a discovered Lithia event inside the correct runtime contexts.
+   *
+   * The call first enters the app-level async context and then the event
+   * context store so event hooks can access the active socket, payload, and
+   * event metadata during middleware and handler execution.
+   *
+   * @param {Socket} socket - Active socket associated with the dispatch.
+   * @param {Event} event - Discovered event manifest to execute.
+   * @param {any[]} args - Raw Socket.IO event arguments forwarded to the event
+   * processor.
+   */
+  dispatch(socket, event, ...args) {
+    void this.app.runWithContext(async () => {
+      const context = {
+        data: args[0],
+        socket,
+        event
+      };
+      eventContextStore.run(context, async () => {
+        await this.processor.process(socket, event, ...args);
+      });
+    });
+  }
+};
+
+// src/transport/server.ts
+var LithiaServer = class {
+  /**
+   * Creates the transport server for a running app instance.
+   *
+   * @param {LithiaApp} app - Runtime app that provides config, route/event
+   * manifests, and async context helpers.
+   */
+  constructor(app) {
+    this.app = app;
+    this.requestProcessor = new LithiaRequestProcessor(this.app);
+    this.eventProcessor = new LithiaEventProcessor(this.app);
+    this._httpServer = this.createServer();
+    this.socketTransport = new LithiaSocketTransport(
+      this.app,
+      this._httpServer,
+      this.eventProcessor
+    );
+  }
+  _httpServer;
+  requestProcessor;
+  eventProcessor;
+  socketTransport;
+  _activeRequests = /* @__PURE__ */ new Set();
+  /**
+   * Returns the set of currently open TCP connections tracked by the server.
+   *
+   * The set is updated from the Node.js `"connection"` event and is used during
+   * shutdown to forcefully destroy lingering sockets after the server stops
+   * accepting new traffic.
+   *
+   * @returns {Set<ActiveRequest>} Tracked open TCP sockets.
+   */
+  get activeRequests() {
+    return this._activeRequests;
+  }
+  /**
+   * Returns the underlying Node.js HTTP or HTTPS server instance.
+   *
+   * @returns {HttpServer | HttpsServer} Active low-level server instance.
+   */
+  get httpServer() {
+    return this._httpServer;
+  }
+  /**
+   * Returns the Socket.IO server attached to the transport.
+   *
+   * @returns {ReturnType<LithiaSocketTransport["server"]>} Active Socket.IO
+   * server instance.
+   */
+  get socketServer() {
+    return this.socketTransport.server;
+  }
+  /**
+   * Starts listening on the configured host and port.
+   *
+   * Repeated calls are idempotent while the underlying server is already
+   * listening. The returned promise resolves on the low-level `"listening"`
+   * event and rejects on the first startup error emitted by Node.js.
+   *
+   * @returns {Promise<void>} Resolves after the transport begins accepting
+   * connections.
+   */
+  async listen() {
+    const { port, host } = this.app.config.http;
+    return new Promise((resolve, reject) => {
+      if (this._httpServer.listening) {
+        return resolve();
+      }
+      const handleError = (error) => {
+        this._httpServer.off("listening", handleListening);
+        reject(error);
+      };
+      const handleListening = () => {
+        this._httpServer.off("error", handleError);
+        resolve();
+      };
+      this._httpServer.once("error", handleError);
+      this._httpServer.once("listening", handleListening);
+      this._httpServer.listen(port, host);
+    });
+  }
+  /**
+   * Closes the Socket.IO transport, stops accepting HTTP traffic, and destroys
+   * any remaining active connections.
+   *
+   * Socket.IO shutdown is attempted first so realtime traffic stops before the
+   * underlying HTTP server is closed. Remaining sockets are then destroyed to
+   * avoid hanging shutdown on keep-alive connections.
+   *
+   * @returns {Promise<void>} Resolves after the transport has been shut down and
+   * tracked connections have been cleared.
+   */
+  async close() {
+    await this.socketTransport.close().catch((error) => {
+      logger.error("Failed to close Socket.IO transport cleanly:", error);
+    });
+    if (!this._httpServer.listening) {
+      for (const socket of this._activeRequests) {
+        socket.destroy();
+      }
+      this._activeRequests.clear();
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      this._httpServer.close((error) => {
+        if (error) return reject(error);
+        resolve();
+      });
+    });
+    for (const socket of this._activeRequests) {
+      socket.destroy();
+    }
+    this._activeRequests.clear();
+  }
+  /**
+   * Creates the underlying HTTP or HTTPS server instance.
+   *
+   * The returned server also tracks active sockets so shutdown can destroy
+   * lingering keep-alive connections after `close()`.
+   *
+   * @returns {HttpServer | HttpsServer} Low-level server configured for the
+   * current app transport.
+   */
+  createServer() {
+    const handler = this.handleRequest();
+    const sslConfig = this.app.config.http.ssl;
+    const server = sslConfig ? createServer(sslConfig, handler) : createServer$1(handler);
+    server.on("connection", (socket) => {
+      this._activeRequests.add(socket);
+      socket.on("close", () => this._activeRequests.delete(socket));
+    });
+    return server;
+  }
+  /**
+   * Creates the low-level Node request handler and bridges it into Lithia's
+   * request context and request pipeline.
+   *
+   * Each incoming Node.js request is wrapped into `LithiaRequest` and
+   * `LithiaResponse`, associated with a route context store, and then processed
+   * inside the app-level async context so route hooks can access the active
+   * request state.
+   *
+   * If request initialization itself fails before the normal request pipeline
+   * takes over, the handler falls back to a minimal JSON `500` response.
+   *
+   * @returns {(req: IncomingMessage, res: ServerResponse) => void} Node.js
+   * request listener bound to the current app instance.
+   */
+  handleRequest() {
+    return (req, res) => {
+      try {
+        const lithiaReq = new LithiaRequest(req, {
+          maxBodySize: this.app.config.http.maxBodySize
+        });
+        const lithiaRes = new LithiaResponse(res);
+        const routeContext = {
+          req: lithiaReq,
+          res: lithiaRes,
+          socketServer: this.socketTransport.server
+        };
+        void this.app.runWithContext(async () => {
+          routeContextStore.run(routeContext, async () => {
+            await this.requestProcessor.process(lithiaReq, lithiaRes);
+          });
+        });
+      } catch (error) {
+        logger.error("Failed to initialize request context:", error);
+        if (!res.headersSent) {
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "application/json");
+        }
+        if (!res.writableEnded) {
+          res.end(
+            JSON.stringify({
+              error: {
+                statusCode: 500,
+                message: "Failed to initialize request handling.",
+                timestamp: (/* @__PURE__ */ new Date()).toISOString()
+              }
+            })
+          );
+        }
+      }
+    };
+  }
+};
+
+// src/runtime/app/dependency-container.ts
+var DependencyContainer = class {
+  dependencies = /* @__PURE__ */ new Map();
+  /**
+   * Stores a dependency by its injection key.
+   *
+   * @param {any} key - Injection token used to identify the dependency.
+   * @param {T} value - Dependency instance stored under `key`.
+   */
+  set(key, value) {
+    this.dependencies.set(key, value);
+  }
+  /**
+   * Returns whether a dependency has been registered.
+   *
+   * @param {any} key - Injection token to test.
+   * @returns {boolean} `true` when the container includes `key`.
+   */
+  has(key) {
+    return this.dependencies.has(key);
+  }
+  /**
+   * Resolves a dependency by key.
+   *
+   * @param {any} key - Injection token to resolve.
+   * @returns {T | undefined} Registered dependency instance, or `undefined`
+   * when the key is absent.
+   */
+  get(key) {
+    return this.dependencies.get(key);
+  }
+  /**
+   * Returns an immutable snapshot of the container contents.
+   *
+   * The returned `Map` is detached from future container mutations, which lets
+   * the runtime execute work against a stable dependency view.
+   *
+   * @returns {Map<any, any>} Shallow copy of the current container contents.
+   */
+  snapshot() {
+    return new Map(this.dependencies);
+  }
+  /**
+   * Returns the underlying mutable container.
+   *
+   * Mutating the returned `Map` mutates the container itself.
+   *
+   * @returns {Map<any, any>} Backing dependency map used by the runtime.
+   */
+  mutable() {
+    return this.dependencies;
+  }
+};
+
+// src/runtime/app/middleware-registry.ts
+var MiddlewareRegistry = class {
+  routeMiddlewares = [];
+  eventMiddlewares = [];
+  /**
+   * Registers a middleware for either the route or event pipeline.
+   *
+   * Route middleware is appended to the global HTTP pipeline. Event
+   * middleware is appended to the global socket event pipeline.
+   *
+   * @param {"route" | "event"} context - Pipeline that should receive the
+   * middleware.
+   * @param {TRouteMiddleware | TEventMiddleware} middleware - Middleware
+   * instance appended to the selected pipeline.
+   */
+  use(context, middleware) {
+    if (context === "route") {
+      this.routeMiddlewares.push(middleware);
+      return;
+    }
+    this.eventMiddlewares.push(middleware);
+  }
+  /**
+   * Returns the registered global route middlewares.
+   *
+   * The returned array is the live registry array and preserves registration
+   * order.
+   *
+   * @returns {TRouteMiddleware[]} Registered route middlewares.
+   */
+  getRoutes() {
+    return this.routeMiddlewares;
+  }
+  /**
+   * Returns the registered global event middlewares.
+   *
+   * The returned array is the live registry array and preserves registration
+   * order.
+   *
+   * @returns {TEventMiddleware[]} Registered event middlewares.
+   */
+  getEvents() {
+    return this.eventMiddlewares;
+  }
+};
+async function fileExists(filePath) {
+  return await access(filePath).then(() => true).catch(() => false);
+}
+async function fileHasMeaningfulModuleContent(filePath) {
+  const source = await readFile(filePath, "utf8");
+  const withoutComments = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+  return withoutComments.trim().length > 0;
+}
+
+// src/runtime/app/server-bootstrap.ts
+async function resolveServerBootstrapPath(outDir, cwd = process.cwd()) {
+  const candidates = [
+    path.join(cwd, outDir, "app", "server.js"),
+    path.join(cwd, outDir, "app", "server.mjs")
+  ];
+  for (const candidate of candidates) {
+    if (await fileExists(candidate) && await fileHasMeaningfulModuleContent(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+async function loadServerBootstrap(filePath) {
+  const mod = await loadModule(filePath);
+  return mod.default;
+}
+function normalizeServerBootstrapCleanup(value) {
+  if (value === void 0) return null;
+  if (typeof value !== "function") {
+    throw new Error(
+      "`app/server.ts` must return either nothing or a cleanup function."
+    );
+  }
+  return async () => {
+    await value();
+  };
+}
+var TaskScheduler = class {
+  /**
+   * Creates a scheduler for the task manifest loaded into the current app
+   * worker.
+   *
+   * @param {TaskCore[]} tasks - Task manifest entries available to the app
+   * runtime.
+   */
+  constructor(tasks) {
+    this.tasks = tasks;
+  }
+  cronJobs = [];
+  /**
+   * Starts all CRON tasks and invokes the callback when a schedule fires.
+   *
+   * Each CRON task must already include a validated `schedule` string. When a
+   * schedule triggers, the scheduler invokes `onTrigger` with the original
+   * task metadata.
+   *
+   * @param {(task: TaskCore) => void} onTrigger - Callback invoked when a CRON
+   * task schedule fires.
+   * @throws {Error} Throws when a CRON task is missing its resolved
+   * `schedule`.
+   */
+  start(onTrigger) {
+    const cronTasks = this.tasks.filter((task) => task.trigger === "CRON");
+    for (const task of cronTasks) {
+      if (!task.schedule) {
+        throw new Error(
+          `CRON task '${task.id}' is missing a resolved schedule.`
+        );
+      }
+      const job = cron.schedule(task.schedule, () => {
+        onTrigger(task);
+      });
+      this.cronJobs.push(job);
+    }
+  }
+  /**
+   * Stops and destroys all registered CRON jobs.
+   *
+   * This is used during app shutdown to ensure scheduled tasks no longer fire
+   * after the runtime begins closing.
+   */
+  stop() {
+    for (const job of this.cronJobs.splice(0)) {
+      job.stop();
+      if ("destroy" in job && typeof job.destroy === "function") {
+        job.destroy();
+      }
+    }
+  }
+};
+
+// src/runtime/app/app-runtime.ts
+var LithiaApp = class {
+  _environment;
+  _config;
+  _routes;
+  _events;
+  _tasks;
+  _isFirstApp;
+  dependencies = new DependencyContainer();
+  middlewares = new MiddlewareRegistry();
+  serverBootstrapCleanup = null;
+  _server;
+  taskScheduler;
+  /**
+   * Creates the app runtime from the worker payload prepared by the Lithia CLI.
+   *
+   * The constructor reads routes, events, tasks, config, and environment from
+   * `workerData`, then initializes the server and task scheduler that run
+   * inside the worker thread.
+   *
+   * @throws {Error} Throws when the runtime is instantiated outside a
+   * Lithia-managed worker thread.
+   */
+  constructor() {
+    this.validateExecutionContext();
+    this._config = workerData.config;
+    this._routes = workerData.routes;
+    this._events = workerData.events;
+    this._tasks = workerData.tasks;
+    this._environment = workerData.environment;
+    this._isFirstApp = workerData.isFirstApp;
+    this._server = new LithiaServer(this);
+    this.taskScheduler = new TaskScheduler(this._tasks);
+  }
+  /**
+   * Returns the resolved application configuration for this runtime instance.
+   */
+  get config() {
+    return this._config;
+  }
+  /**
+   * Returns the environment mode assigned to this app worker.
+   */
+  get environment() {
+    return this._environment;
+  }
+  /**
+   * Returns the discovered route manifest loaded into this app worker.
+   */
+  get routes() {
+    return this._routes;
+  }
+  /**
+   * Returns the discovered socket event manifest loaded into this app worker.
+   */
+  get events() {
+    return this._events;
+  }
+  /**
+   * Returns the discovered task manifest loaded into this app worker.
+   *
+   * Cron-backed tasks follow the conventions described in
+   * [Async Tasks](https://lithiajs.org/docs/latest/async-tasks).
+   */
+  get tasks() {
+    return this._tasks;
+  }
+  /**
+   * Returns the global HTTP middlewares registered for every route pipeline.
+   */
+  get globalRouteMiddlewares() {
+    return this.middlewares.getRoutes();
+  }
+  /**
+   * Returns the global socket middlewares registered for every event pipeline.
+   */
+  get globalEventMiddlewares() {
+    return this.middlewares.getEvents();
+  }
+  /**
+   * Returns whether this worker is the first app instance in the current
+   * process lifecycle.
+   *
+   * Lithia uses this flag to limit one-time logs and similar side effects to a
+   * single runtime instance.
+   */
+  get isFirstApp() {
+    return this._isFirstApp;
+  }
+  /**
+   * Runs work inside an immutable snapshot of the app dependency container.
+   *
+   * Use this for request handling or background work that should only resolve
+   * dependencies that were already registered during bootstrap.
+   *
+   * @param {() => Promise<T>} fn - Async work to execute inside the Lithia
+   * context.
+   * @returns {Promise<T>} The value resolved by `fn`.
+   */
+  runWithContext(fn) {
+    return this.runWithContainer(this.dependencies.snapshot(), fn);
+  }
+  /**
+   * Runs work inside the mutable app dependency container.
+   *
+   * This is primarily used during app bootstrap, when new dependencies may be
+   * registered with `provide()`.
+   *
+   * This method is typically used while running `src/app/server.ts`. See
+   * [Project Structure](https://lithiajs.org/docs/latest/project-structure)
+   * and [Deploying](https://lithiajs.org/docs/latest/deploying).
+   *
+   * @param {() => Promise<T>} fn - Async work to execute inside the mutable
+   * Lithia context.
+   * @returns {Promise<T>} The value resolved by `fn`.
+   */
+  runWithMutableContext(fn) {
+    return this.runWithContainer(this.dependencies.mutable(), fn);
+  }
+  /**
+   * Runs work inside a Lithia context backed by the provided dependency
+   * container.
+   *
+   * @param {Map<any, any>} container - Dependency container exposed to the
+   * current context.
+   * @param {() => Promise<T>} fn - Async work to execute inside the context.
+   * @returns {Promise<T>} The value resolved by `fn`.
+   */
+  runWithContainer(container, fn) {
+    const context = {
+      container,
+      config: this.config
+    };
+    return runInLithiaContext(context, fn);
+  }
+  /**
+   * Registers a dependency in the app container.
+   *
+   * Dependencies registered here become available through the Lithia context
+   * for routes, events, tasks, and startup hooks.
+   *
+   * @param {InjectionKey<T>} key - Token used to store and resolve the
+   * dependency.
+   * @param {T} value - Dependency instance associated with `key`.
+   */
+  provide(key, value) {
+    this.dependencies.set(key, value);
+  }
+  /**
+   * Registers a global middleware for routes or events.
+   *
+   * Route middlewares run for every HTTP route. Event middlewares run for
+   * every socket event.
+   *
+   * @param {"route" | "event"} context - Middleware pipeline that should
+   * receive the registration.
+   * @param {K extends "route" ? RouteMiddleware : EventMiddleware} middleware
+   * - Middleware implementation to append to the selected global pipeline.
+   */
+  use(context, middleware) {
+    this.middlewares.use(context, middleware);
+  }
+  /**
+   * Starts the app runtime.
+   *
+   * The startup sequence is:
+   * 1. run optional `app/server.ts`
+   * 2. start the HTTP/socket server
+   * 3. register CRON-backed tasks
+   * 4. announce readiness
+   *
+   * `app/server.ts` participates in the startup lifecycle described in
+   * [Deploying](https://lithiajs.org/docs/latest/deploying) and
+   * [Project Structure](https://lithiajs.org/docs/latest/project-structure).
+   *
+   * @returns {Promise<void>} Resolves after the server is listening and cron
+   * tasks have been registered.
+   * @throws {unknown} Rethrows any startup failure from bootstrap loading,
+   * server startup, or task registration.
+   */
+  async start() {
+    this.executeOnce(() => logger.info("Starting Lithia server..."));
+    try {
+      await this.runServerBootstrapIfPresent();
+      await this._server.listen();
+      this.taskScheduler.start((task) => {
+        parentPort?.postMessage({
+          type: "invoke",
+          taskId: task.id,
+          async: true,
+          executionId: randomUUID(),
+          args: [],
+          source: "CRON",
+          attempt: 0
+        });
+      });
+      this.executeOnce(
+        () => logger.ready(`Lithia is ready on port ${this.config.http.port}`)
+      );
+    } catch (error) {
+      this.executeOnce(() => logger.error("Failed to start Lithia server."));
+      throw error;
+    }
+  }
+  /**
+   * Stops the app runtime and runs all registered cleanup hooks.
+   *
+   * The shutdown sequence runs the optional cleanup returned by
+   * `src/app/server.ts`, stops cron scheduling, and then closes the server.
+   *
+   * @returns {Promise<void>} Resolves after cleanup hooks and server shutdown
+   * finish.
+   */
+  async stop() {
+    await this.runServerBootstrapCleanup();
+    this.taskScheduler.stop();
+    await this._server.close();
+  }
+  /**
+   * Loads and runs `app/server.ts` when the file exists in the build output.
+   *
+   * If the bootstrap exports a cleanup callback, the callback is normalized
+   * and stored for `stop()`.
+   *
+   * @returns {Promise<void>} Resolves after the bootstrap has finished.
+   */
+  async runServerBootstrapIfPresent() {
+    const filePath = await resolveServerBootstrapPath(this.config.outDir);
+    if (!filePath) return;
+    const bootstrap2 = await loadServerBootstrap(filePath);
+    const cleanup = await this.runWithMutableContext(() => bootstrap2());
+    this.serverBootstrapCleanup = normalizeServerBootstrapCleanup(
+      cleanup
+    );
+  }
+  /**
+   * Runs the cleanup returned by `app/server.ts`, if one was registered.
+   *
+   * Cleanup errors are logged and do not prevent the runtime from continuing
+   * its shutdown flow.
+   *
+   * @returns {Promise<void>} Resolves after the cleanup callback completes or
+   * is skipped.
+   */
+  async runServerBootstrapCleanup() {
+    if (!this.serverBootstrapCleanup) return;
+    try {
+      await this.serverBootstrapCleanup();
+    } catch (error) {
+      logger.error("Failed to clean up app/server.ts bootstrap.", error);
+    } finally {
+      this.serverBootstrapCleanup = null;
+    }
+  }
+  /**
+   * Restricts one-time logs to the first app instance for a given lifecycle.
+   *
+   * This prevents duplicated startup and failure logs when multiple app
+   * workers share the same lifecycle but only one instance should announce
+   * framework-level state changes.
+   *
+   * @param {() => void} fn - Side effect to run only for the first app
+   * instance.
+   */
+  executeOnce(fn) {
+    if (this.isFirstApp) {
+      fn();
+    }
+  }
+  /**
+   * Ensures the app runtime only executes inside a Lithia-managed worker.
+   *
+   * The runtime depends on `workerData` prepared by the Lithia CLI and on the
+   * worker messaging model used by the app worker entrypoint. Direct
+   * instantiation on the main thread or inside an unrelated worker is not
+   * supported.
+   *
+   * @throws {Error} Throws when the runtime runs on the main thread or inside
+   * a worker not created by the Lithia CLI.
+   */
+  validateExecutionContext() {
+    if (isMainThread) {
+      throw new Error(
+        "Execution Error: LithiaApp cannot be instantiated on the main thread. It must run within a Worker Thread."
+      );
+    }
+    if (workerData?.managedBy !== "lithia") {
+      throw new Error(
+        "Compatibility Error: LithiaApp must be managed by the Lithia CLI. Independent execution is not supported."
+      );
+    }
+  }
+};
+
+// src/runtime/workers/app-worker.ts
+var isInitialized = false;
+async function bootstrap() {
+  if (isInitialized) return;
+  isInitialized = true;
+  logger.debug("Initializing Lithia background worker...");
+  const app = new LithiaApp();
+  try {
+    await app.start();
+    parentPort?.postMessage({ type: "ready" });
+  } catch (error) {
+    try {
+      await app.stop();
+    } catch (stopError) {
+      logger.error(
+        "Failed to stop Lithia app cleanly after startup failure:",
+        stopError
+      );
+    }
+    const errorPayload = error instanceof LithiaError ? {
+      name: error.name,
+      message: error.message,
+      context: error.context,
+      stack: error.stack
+    } : {
+      name: error?.name ?? "UnknownWorkerError",
+      message: String(error?.message ?? error),
+      stack: error?.stack
+    };
+    parentPort?.postMessage({ type: "error", error: errorPayload });
+    if (!(error instanceof LithiaError)) {
+      throw error;
+    }
+    return;
+  }
+  const shutdown = async () => {
+    try {
+      await app.stop();
+    } catch {
+    } finally {
+      process.exit(0);
+    }
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+}
+bootstrap().catch((error) => {
+  logger.error("Fatal exception in Lithia worker:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=app-worker.mjs.map
+//# sourceMappingURL=app-worker.mjs.map