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

package/dist/_index.mjs

@@ -0,0 +1,2106 @@
+import fs4, { readFile, rm, access } from 'fs/promises';
+import path from 'path';
+import { parseEnv } from 'util';
+import { isMainThread, Worker } from 'worker_threads';
+import { logger, green, red } from '@lithia-js/utils';
+import sms from 'source-map-support';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+import fg from 'fast-glob';
+import cron from 'node-cron';
+import * as swc from '@swc/core';
+import { loadConfig as loadConfig$1 } from 'c12';
+import { klona } from 'klona';
+
+// 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/app/client.ts
+var RouteNotFoundError = class extends LithiaClientError {
+  constructor(m, d) {
+    super(m, 404, d);
+  }
+};
+
+// src/errors/internal/context.ts
+var NotInLithiaContextError = class extends LithiaError {
+  constructor() {
+    super("Lithia hooks must be used within a managed invocation.");
+  }
+};
+
+// src/errors/internal/loader.ts
+var ManifestVersionMismatchError = class extends LithiaError {
+  constructor(expectedVersion, foundVersion) {
+    super(
+      `Manifest version mismatch: expected '${expectedVersion}', but found '${foundVersion}'. Rebuild required.`
+    );
+  }
+};
+
+// package.json
+var package_default = {
+  version: "1.0.0-canary.21"};
+
+// src/meta.ts
+var version = package_default.version;
+
+// src/discovery/events.ts
+var withBase = (targetPath, base) => {
+  if (!base || base === "/") return targetPath;
+  return `${base.replace(/\/$/, "")}/${targetPath.replace(/^\//, "")}`;
+};
+var EventConvention = class {
+  /**
+   * Removes the leading event root from a discovered event file path.
+   *
+   * @param {string} filePath - Relative file path returned by the scanner.
+   * @returns {string} Event-relative path used for name normalization.
+   */
+  extractEventPath(filePath) {
+    return filePath.replace(/\\/g, "/").replace(/^(app\/)?events\//, "");
+  }
+};
+var EventPathTransformer = class {
+  removeExt = /\.(mts|mjs|ts|js)$/i;
+  removeGroups = /\(([^([\\/]+)\)[\\/]/g;
+  /**
+   * Removes extensions, grouping segments, duplicate separators, and leading
+   * or trailing slashes from an event path fragment.
+   *
+   * @param {string} pathStr - Event-relative path fragment to normalize.
+   * @returns {string} Canonical event path without file extension or groups.
+   */
+  normalize(pathStr) {
+    const normalized = pathStr.replace(/\\/g, "/").replace(this.removeExt, "").replace(this.removeGroups, "");
+    return normalized.replace(/\/+/g, "/").replace(/^\/|\/$/g, "");
+  }
+  /**
+   * Converts a normalized path into an absolute path with an optional global
+   * prefix.
+   *
+   * @param {string} pathStr - Path fragment to prefix and canonicalize.
+   * @param {string} globalPrefix - Optional base path applied before
+   * normalization.
+   * @returns {string} Absolute path with a single leading slash and no
+   * trailing slash unless the path is root.
+   */
+  normalizePath(pathStr, globalPrefix = "") {
+    const combined = withBase(pathStr, globalPrefix);
+    const noTrailing = combined.endsWith("/") && combined.length > 1 ? combined.slice(0, -1) : combined;
+    return noTrailing.startsWith("/") ? noTrailing : `/${noTrailing}`;
+  }
+};
+var EventProcessor = class {
+  constructor(transformer = new EventPathTransformer(), convention = new EventConvention()) {
+    this.transformer = transformer;
+    this.convention = convention;
+  }
+  /**
+   * Processes multiple discovered event files into manifest entries.
+   *
+   * @param {FileInfo[]} files - Discovered event files to transform.
+   * @returns {Event[]} Runtime event entries derived from the input files.
+   */
+  process(files) {
+    return files.map((file) => this.processEventFile(file));
+  }
+  /**
+   * Resolves one discovered event file into a runtime manifest entry.
+   *
+   * Single-segment files produce bare event names such as `connection` or
+   * `disconnect`. Nested files produce colon-delimited names such as
+   * `chat:ping`, except for trailing `connection` and `disconnect`, which keep
+   * their lifecycle names.
+   *
+   * @param {FileInfo} file - Discovered event file to transform.
+   * @returns {Event} Manifest entry used by the socket runtime.
+   */
+  processEventFile(file) {
+    const intermediate = this.convention.extractEventPath(file.path);
+    const normalized = this.transformer.normalize(intermediate);
+    const parts = normalized.split("/").filter((part) => part.length > 0);
+    let eventName = "";
+    if (parts.length === 1) {
+      eventName = parts[0];
+    } else if (parts.length > 1) {
+      const last = parts[parts.length - 1];
+      eventName = last === "connection" || last === "disconnect" ? last : parts.join(":");
+    }
+    return {
+      name: eventName,
+      filePath: file.fullPath,
+      namespace: eventName.includes(":") ? eventName.split(":")[0] : null
+    };
+  }
+};
+var EventManifestGenerator = class {
+  constructor(processor = new EventProcessor()) {
+    this.processor = processor;
+  }
+  /**
+   * Generates `events.json` from scanned build output files.
+   *
+   * The generator filters scanned files to event handler locations, converts
+   * them into runtime event entries, and writes a versioned manifest that is
+   * later loaded by the host runtime.
+   *
+   * @param {string} outRoot - Build output directory that receives the
+   * manifest.
+   * @param {FileInfo[]} scannedFiles - Files scanned from the compiled output
+   * tree.
+   * @returns {Promise<EventsManifest | null>} The generated manifest, or
+   * `null` when no event files are present.
+   * @throws {Error} Throws when the manifest directory cannot be created or
+   * the manifest file cannot be written.
+   */
+  async generateManifest(outRoot, scannedFiles) {
+    const eventFiles = scannedFiles.filter((file) => {
+      const normalized = file.path.split(path.sep).join("/");
+      return normalized.includes("events/") || normalized.includes("app/events/");
+    });
+    if (eventFiles.length === 0) return null;
+    const events = this.processor.process(eventFiles);
+    const manifest = { version, events };
+    const manifestPath = path.join(outRoot, "events.json");
+    try {
+      await fs4.mkdir(path.dirname(manifestPath), { recursive: true });
+      await fs4.writeFile(
+        manifestPath,
+        JSON.stringify(manifest, null, 2),
+        "utf-8"
+      );
+    } catch (error) {
+      throw new Error(`Failed to write events manifest: ${error}`);
+    }
+    return manifest;
+  }
+};
+var withBase2 = (routePath, base) => {
+  if (!base || base === "/") return routePath;
+  return `${base.replace(/\/$/, "")}/${routePath.replace(/^\//, "")}`;
+};
+var withLeadingSlash = (routePath) => routePath.startsWith("/") ? routePath : `/${routePath}`;
+var withoutTrailingSlash = (routePath) => routePath.endsWith("/") && routePath.length > 1 ? routePath.slice(0, -1) : routePath;
+var RouteConvention = class {
+  routeRegex = /(?:^|[\\/])route(\.(delete|get|head|options|patch|post|put))?\.(mts|mjs|ts|js)$/i;
+  /**
+   * Extracts the optional HTTP method suffix from a route file path.
+   *
+   * @param {string} filePath - Route-relative file path returned by the
+   * scanner.
+   * @returns {ExtractedMethod} Inferred method and the remaining logical path.
+   */
+  extractMethod(filePath) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const match = normalizedPath.match(this.routeRegex);
+    const methodStr = match?.[2]?.toUpperCase();
+    const rawPath = normalizedPath.replace(this.routeRegex, "");
+    return {
+      method: methodStr || null,
+      updatedPath: rawPath
+    };
+  }
+};
+var RoutePathTransformer = class {
+  removeExt = /\.(mts|mjs|ts|js)$/i;
+  removeGroups = /\(([^([\\/]+)\)[\\/]/g;
+  catchAllNamed = /\[\.\.\.(\w+)\]/g;
+  catchAll = /\[\.\.\.\]/g;
+  dynamic = /\[([^/\]]+)\]/g;
+  dynamicDetector = /:\w+|\*\*/;
+  routeParam = /:(\w+)/g;
+  /**
+   * Converts a route file path into Lithia's internal route path format.
+   *
+   * Grouping segments are removed, `[param]` becomes `:param`, `[...name]`
+   * becomes `**:name`, and `[...]` becomes `**`.
+   *
+   * @param {string} filePath - Route path fragment after removing the route
+   * filename pattern.
+   * @returns {string} Internal route path used by later normalization steps.
+   */
+  transformFilePath(filePath) {
+    let result = filePath.replace(/\\/g, "/").replace(this.removeExt, "").replace(this.removeGroups, "");
+    result = result.replace(this.catchAllNamed, "**:$1");
+    result = result.replace(this.catchAll, "**");
+    result = result.replace(this.dynamic, ":$1");
+    return result;
+  }
+  /**
+   * Converts an internal route path into a canonical public route path.
+   *
+   * @param {string} pathStr - Internal route path to normalize.
+   * @param {string} globalPrefix - Optional global prefix applied before
+   * normalization.
+   * @returns {string} Public route path with a leading slash and no trailing
+   * slash unless the path is root.
+   */
+  normalizePath(pathStr, globalPrefix = "") {
+    const combined = withBase2(pathStr, globalPrefix);
+    const noTrailing = withoutTrailingSlash(combined);
+    return withLeadingSlash(noTrailing);
+  }
+  /**
+   * Detects whether a route path contains dynamic or catch-all segments.
+   *
+   * @param {string} pathStr - Canonical route path to inspect.
+   * @returns {boolean} `true` when the route contains `:param` or `**`
+   * segments.
+   */
+  isDynamicRoute(pathStr) {
+    return this.dynamicDetector.test(pathStr);
+  }
+  /**
+   * Generates the runtime matcher regex source for a canonical route path.
+   *
+   * Named parameters become single-segment capture groups, and catch-all
+   * segments become greedy capture groups.
+   *
+   * @param {string} pathStr - Canonical route path to convert.
+   * @returns {string} Anchored regex source used by the route matcher.
+   */
+  generateRouteRegex(pathStr) {
+    let escaped = pathStr.replace(/\//g, "\\/");
+    escaped = escaped.replace(/\*\*:\w+/g, "(.*)");
+    escaped = escaped.replace(/\*\*/g, "(.*)");
+    const regexBody = escaped.replace(this.routeParam, "([^\\/]+)");
+    return `^${regexBody}$`;
+  }
+};
+var RouteProcessor = class {
+  constructor(transformer = new RoutePathTransformer(), convention = new RouteConvention()) {
+    this.transformer = transformer;
+    this.convention = convention;
+  }
+  /**
+   * Resolves one discovered route file into a runtime manifest entry.
+   *
+   * The processor strips the route root, extracts the optional method suffix,
+   * normalizes dynamic and catch-all segments, computes whether the route is
+   * dynamic, and generates the regex source used by request matching.
+   *
+   * @param {FileInfo} file - Discovered route file to transform.
+   * @returns {Route} Manifest entry consumed by the HTTP runtime.
+   */
+  processRouteFile(file) {
+    const logicalPath = file.path.replace(/^(.*[\\/])?routes[\\/]/, "");
+    const extracted = this.convention.extractMethod(logicalPath);
+    const internalPath = this.transformer.transformFilePath(
+      extracted.updatedPath
+    );
+    const finalPath = this.transformer.normalizePath(internalPath, "");
+    const dynamic = this.transformer.isDynamicRoute(finalPath);
+    const regex = this.transformer.generateRouteRegex(finalPath);
+    return {
+      method: extracted.method?.toString(),
+      path: finalPath,
+      dynamic,
+      filePath: file.fullPath,
+      regex
+    };
+  }
+};
+var RouteManifestGenerator = class {
+  constructor(processor = new RouteProcessor()) {
+    this.processor = processor;
+  }
+  /**
+   * Generates `routes.json` from scanned build output files.
+   *
+   * The generator filters scanned files to route handler locations, converts
+   * them into runtime route entries, and writes a versioned manifest that is
+   * later loaded by the host runtime.
+   *
+   * @param {string} outRoot - Build output directory that receives the
+   * manifest.
+   * @param {FileInfo[]} scannedFiles - Files scanned from the compiled output
+   * tree.
+   * @returns {Promise<RoutesManifest>} Generated route manifest.
+   * @throws {Error} Throws when the manifest directory cannot be created or
+   * the manifest file cannot be written.
+   */
+  async generateManifest(outRoot, scannedFiles) {
+    const routeFiles = scannedFiles.filter((file) => {
+      const normalized = file.path.split(path.sep).join("/");
+      return normalized.includes("routes/") || normalized.includes("app/routes/");
+    });
+    const routes = routeFiles.map(
+      (file) => this.processor.processRouteFile(file)
+    );
+    const manifest = { version, routes };
+    const manifestPath = path.join(outRoot, "routes.json");
+    try {
+      await fs4.mkdir(outRoot, { recursive: true });
+      await fs4.writeFile(
+        manifestPath,
+        JSON.stringify(manifest, null, 2),
+        "utf-8"
+      );
+    } catch (error) {
+      throw new Error(`Failed to write routes manifest: ${error}`);
+    }
+    return manifest;
+  }
+};
+var FileScanner = class {
+  /**
+   * Scans the target directory and returns normalized file metadata.
+   *
+   * The scanner resolves the target directory from `process.cwd()`, applies
+   * include and ignore globs through `fast-glob`, returns only files, excludes
+   * dotfiles, normalizes relative paths to forward slashes, and sorts the
+   * result by relative path for deterministic downstream processing.
+   *
+   * @param {string[]} pathComponents - Path segments resolved from the current
+   * working directory to the scan root.
+   * @param {ScanOptions} options - Optional include and ignore glob patterns.
+   * @returns {Promise<FileInfo[]>} Sorted file metadata entries relative to
+   * the scan root.
+   */
+  async scanDir(pathComponents, options = {}) {
+    const targetPath = path.resolve(process.cwd(), ...pathComponents);
+    const patterns = options.include && options.include.length > 0 ? options.include : ["**/*.{ts,js,mts,mjs}"];
+    const entries = await fg(patterns, {
+      cwd: targetPath,
+      ignore: options.ignore ?? [],
+      absolute: true,
+      onlyFiles: true,
+      dot: false
+    });
+    const fileInfos = entries.map((fullPath) => ({
+      path: path.relative(targetPath, fullPath).replace(/\\/g, "/"),
+      fullPath
+    }));
+    return fileInfos.sort((a, b) => a.path.localeCompare(b.path));
+  }
+};
+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;
+}
+function toOutputFilePath(root, relativePath) {
+  return path.join(root, relativePath).replace(/\.ts$/, ".js").replace(/\.mts$/, ".mjs");
+}
+
+// src/discovery/tasks.ts
+var TaskConvention = class {
+  taskRegex = /^(.*?)(?:\.(cron))?\.(mts|mjs|ts|js)$/i;
+  /**
+   * Extracts the task trigger type and raw identifier from a task file path.
+   *
+   * The optional `.cron` marker changes the trigger from `ON_DEMAND` to
+   * `CRON`.
+   *
+   * @param {string} filePath - Task-relative file path returned by the
+   * scanner.
+   * @returns {ExtractedTask} Task trigger metadata derived from the filename.
+   */
+  extractTask(filePath) {
+    const cleanPath = filePath.replace(/\\/g, "/").replace(/^(app\/)?tasks\//, "");
+    const match = cleanPath.match(this.taskRegex);
+    const isCron = match?.[2]?.toLowerCase() === "cron";
+    const rawName = match?.[1] || cleanPath;
+    return {
+      trigger: isCron ? "CRON" : "ON_DEMAND",
+      rawName
+    };
+  }
+};
+var TaskPathTransformer = class {
+  removeGroups = /\(([^([\\/]+)\)[\\/]/g;
+  /**
+   * Converts a raw task path into Lithia's colon-delimited task identifier.
+   *
+   * Grouping segments are removed and remaining path segments are joined with
+   * colons.
+   *
+   * @param {string} rawName - Task-relative name extracted from the file path.
+   * @returns {string} Stable runtime task identifier.
+   */
+  normalizeIdentifier(rawName) {
+    const withoutGroups = rawName.replace(this.removeGroups, "");
+    return withoutGroups.replace(/\\/g, "/").split("/").filter((part) => part.length > 0).join(":");
+  }
+  /**
+   * Converts a task identifier into a human-readable display label.
+   *
+   * @param {string} identifier - Colon-delimited task identifier.
+   * @returns {string} Space-delimited display name with capitalized segments.
+   */
+  formatDisplayName(identifier) {
+    return identifier.split(":").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  }
+};
+var TaskProcessor = class {
+  constructor(convention = new TaskConvention(), transformer = new TaskPathTransformer()) {
+    this.convention = convention;
+    this.transformer = transformer;
+  }
+  /**
+   * Processes multiple discovered task files into manifest entries.
+   *
+   * @param {FileInfo[]} files - Discovered task files to transform.
+   * @returns {TaskCore[]} Runtime task entries derived from the input files.
+   */
+  process(files) {
+    return files.map((file) => this.processTaskFile(file));
+  }
+  /**
+   * Resolves one discovered task file into a runtime manifest entry.
+   *
+   * CRON metadata such as `schedule` and `retries` is attached later during
+   * manifest generation after the module can be loaded from the build output.
+   *
+   * @param {FileInfo} file - Discovered task file to transform.
+   * @returns {TaskCore} Manifest entry with identifier, trigger, and module
+   * path.
+   */
+  processTaskFile(file) {
+    const extracted = this.convention.extractTask(file.path);
+    const id = this.transformer.normalizeIdentifier(extracted.rawName);
+    return {
+      id,
+      trigger: extracted.trigger,
+      filePath: file.fullPath,
+      schedule: void 0,
+      retries: void 0
+    };
+  }
+};
+var TaskManifestGenerator = class {
+  constructor(processor = new TaskProcessor()) {
+    this.processor = processor;
+  }
+  /**
+   * Generates `tasks.json` from scanned build output files.
+   *
+   * The generator filters scanned files to task handler locations, converts
+   * them into runtime task entries, resolves CRON metadata from compiled task
+   * modules, and writes a versioned manifest that is later loaded by the host
+   * runtime.
+   *
+   * @param {string} outRoot - Build output directory that receives the
+   * manifest.
+   * @param {FileInfo[]} scannedFiles - Files scanned from the compiled output
+   * tree.
+   * @returns {Promise<TasksManifest | null>} The generated manifest, or
+   * `null` when no task files are present.
+   * @throws {Error} Throws when task metadata is invalid or when the manifest
+   * file cannot be written.
+   */
+  async generateManifest(outRoot, scannedFiles) {
+    const taskFiles = scannedFiles.filter((file) => {
+      const normalized = file.path.split(path.sep).join("/");
+      return normalized.includes("tasks/") || normalized.includes("app/tasks/");
+    });
+    if (taskFiles.length === 0) return null;
+    const tasks = await this.attachCronSchedules(
+      this.processor.process(taskFiles)
+    );
+    const manifest = { version, tasks };
+    const manifestPath = path.join(outRoot, "tasks.json");
+    try {
+      await fs4.mkdir(path.dirname(manifestPath), { recursive: true });
+      await fs4.writeFile(
+        manifestPath,
+        JSON.stringify(manifest, null, 2),
+        "utf-8"
+      );
+    } catch (error) {
+      throw new Error(`Failed to write tasks manifest: ${error}`);
+    }
+    return manifest;
+  }
+  /**
+   * Loads CRON metadata for discovered tasks and removes empty task modules.
+   *
+   * Files without meaningful module content are skipped entirely. CRON tasks
+   * are dynamically imported so their `schedule` and optional `retries`
+   * exports can be validated and attached to the manifest.
+   *
+   * @param {TaskCore[]} tasks - Task entries produced by the task processor.
+   * @returns {Promise<TaskCore[]>} Task entries ready to be written to the
+   * manifest.
+   * @throws {Error} Throws when a CRON task exports an invalid schedule.
+   */
+  async attachCronSchedules(tasks) {
+    const resolvedTasks = await Promise.all(
+      tasks.map(async (task) => {
+        if (!await fileHasMeaningfulModuleContent(task.filePath)) {
+          return null;
+        }
+        if (task.trigger !== "CRON") return task;
+        const { schedule, retries } = await this.readCronConfig(task.filePath);
+        if (!cron.validate(schedule)) {
+          throw new Error(
+            `Invalid cron schedule '${schedule}' for task '${task.id}'.`
+          );
+        }
+        return {
+          ...task,
+          schedule,
+          retries
+        };
+      })
+    );
+    return resolvedTasks.filter((task) => task !== null);
+  }
+  /**
+   * Reads and validates CRON-specific exports from a compiled task module.
+   *
+   * The module is imported with a cache-busting query string so repeated build
+   * runs do not reuse a stale module instance.
+   *
+   * @param {string} filePath - Compiled task module path to import.
+   * @returns {Promise<{ schedule: string; retries: number }>} Validated CRON
+   * configuration attached to the task manifest.
+   * @throws {Error} Throws when `schedule` is missing or not a string, or when
+   * `retries` is not a non-negative integer.
+   */
+  async readCronConfig(filePath) {
+    const fileUrl = new URL(pathToFileURL(filePath).href);
+    fileUrl.searchParams.set("t", `${Date.now()}`);
+    const mod = await import(fileUrl.href);
+    if (!mod.schedule || typeof mod.schedule !== "string") {
+      throw new Error(
+        `CRON task '${filePath}' must export 'schedule' as a string.`
+      );
+    }
+    if (mod.retries !== void 0 && (!Number.isInteger(mod.retries) || mod.retries < 0)) {
+      throw new Error(
+        `CRON task '${filePath}' must export 'retries' as a non-negative integer.`
+      );
+    }
+    return {
+      schedule: mod.schedule,
+      retries: mod.retries ?? 0
+    };
+  }
+};
+async function compileSourceFiles(files, config) {
+  const { compilerOptions } = await fs4.readFile(path.join(process.cwd(), "tsconfig.json"), "utf-8").then((data) => JSON.parse(data));
+  await Promise.all(
+    files.map(async (file) => {
+      const targetPath = toOutputFilePath(config.outRoot, file.path);
+      await fs4.mkdir(path.dirname(targetPath), { recursive: true });
+      const output = await swc.transformFile(file.fullPath, {
+        jsc: {
+          parser: {
+            syntax: "typescript",
+            dynamicImport: true
+          },
+          target: "esnext",
+          baseUrl: path.resolve(process.cwd(), compilerOptions.baseUrl || "."),
+          paths: {
+            ...compilerOptions.paths || {}
+          }
+        },
+        module: {
+          type: "es6",
+          resolveFully: true
+        },
+        sourceMaps: true
+      });
+      await fs4.writeFile(targetPath, output.code);
+      if (output.map) {
+        await fs4.writeFile(`${targetPath}.map`, output.map);
+      }
+    })
+  );
+}
+async function generateLithiaTypes(projectRoot, registry) {
+  const dotLithiaDir = path.join(projectRoot, ".lithia");
+  const imports = [];
+  const moduleAugmentations = [];
+  for (const [category, definitions] of Object.entries(registry)) {
+    if (!definitions || definitions.length === 0) continue;
+    const interfaceName = `Lithia${category.charAt(0).toUpperCase() + category.slice(1)}`;
+    const interfaceLines = [];
+    for (const def of definitions) {
+      const typeAlias = `${category}_${toPascalCase(def.identifier)}`;
+      const importPath = relativeImportPath(dotLithiaDir, def.filePath);
+      const member = def.exportName || "default";
+      imports.push(
+        `import { ${member} as ${typeAlias} } from "${importPath}";`
+      );
+      interfaceLines.push(`    "${def.identifier}": typeof ${typeAlias};`);
+    }
+    moduleAugmentations.push(
+      `  interface ${interfaceName} {
+${interfaceLines.join("\n")}
+  }`
+    );
+  }
+  const content = [
+    "/* eslint-disable */",
+    "/* This file is auto-generated by Lithia. Do not edit manually. */",
+    imports.join("\n"),
+    '\ndeclare module "@lithia-js/core" {',
+    moduleAugmentations.join("\n\n"),
+    "}"
+  ].join("\n");
+  const lithiaTypesPath = path.join(dotLithiaDir, "lithia.d.ts");
+  await fs4.mkdir(dotLithiaDir, { recursive: true });
+  await fs4.writeFile(lithiaTypesPath, content, "utf-8");
+}
+function toPascalCase(str) {
+  return str.replace(/[^a-zA-Z0-9]/g, "-").replace(/(^\w|-\w)/g, (match) => match.replace("-", "").toUpperCase());
+}
+function relativeImportPath(from, to) {
+  let rel = path.relative(from, to).replace(/\\/g, "/");
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel.replace(/\.(ts|mts|js|mjs)$/, "");
+}
+
+// src/build/build-orchestrator.ts
+var BuildOrchestrator = class {
+  /**
+   * Scans the source tree for buildable files.
+   */
+  scanner = new FileScanner();
+  /**
+   * Generates the route manifest consumed at runtime.
+   */
+  routeGenerator = new RouteManifestGenerator();
+  /**
+   * Generates the event manifest consumed at runtime.
+   */
+  eventGenerator = new EventManifestGenerator();
+  /**
+   * Generates the task manifest consumed at runtime.
+   */
+  taskGenerator = new TaskManifestGenerator();
+  /**
+   * Runs the full build pipeline for a Lithia application.
+   *
+   * The build flow removes the previous output directory, scans source files,
+   * compiles them into the output tree, generates runtime manifests, emits
+   * optional OpenAPI artifacts, and writes generated types for discovered
+   * tasks.
+   *
+   * @param {BuildConfig} config - Build inputs that define the source root,
+   * output root, and optional OpenAPI generation settings.
+   * @returns {Promise<void>} Resolves after every build artifact has been
+   * generated.
+   * @throws {Error} Throws when no source files are found or when any build
+   * step fails.
+   */
+  async build(config) {
+    await rm(config.outRoot, { recursive: true, force: true });
+    const allFiles = await this.scanner.scanDir([config.sourceDir], {
+      include: ["**/*.{ts,js,mts,mjs}"],
+      ignore: ["**/node_modules/**", "**/*.{test|spec}.ts", "**/.*", "dist/**"]
+    });
+    if (allFiles.length === 0) {
+      throw new Error(`No source files found in ${config.sourceDir}`);
+    }
+    await compileSourceFiles(allFiles, config);
+    const distFiles = allFiles.map((file) => ({
+      ...file,
+      fullPath: path.join(
+        process.cwd(),
+        toOutputFilePath(config.outRoot, file.path)
+      )
+    }));
+    const [routesManifest, , tasks] = await Promise.all([
+      this.routeGenerator.generateManifest(config.outRoot, distFiles),
+      this.eventGenerator.generateManifest(config.outRoot, distFiles),
+      this.taskGenerator.generateManifest(config.outRoot, distFiles)
+    ]);
+    await this.generateOpenAPIArtifactsIfEnabled(config, routesManifest.routes);
+    const registry = this.createRegistry(allFiles, tasks?.tasks || []);
+    if (Object.keys(registry).length > 0) {
+      await generateLithiaTypes(process.cwd(), registry);
+    }
+  }
+  /**
+   * Creates the type generation registry for discovered async tasks.
+   *
+   * The registry maps runtime task identifiers back to source file paths so
+   * generated types reference the original task modules instead of compiled
+   * output files. Task conventions are described in
+   * [Async Tasks](https://lithiajs.org/docs/latest/async-tasks).
+   *
+   * @param {{ path: string; fullPath: string }[]} allFiles - Source files
+   * scanned before compilation.
+   * @param {TaskCore[]} tasks - Runtime task manifest entries generated from
+   * compiled files.
+   * @returns {GeneratorRegistry} Type generation metadata keyed by task
+   * identifier, or an empty registry when no tasks are present.
+   */
+  createRegistry(allFiles, tasks) {
+    if (tasks.length === 0) return {};
+    const sourceTaskFiles = allFiles.filter((file) => {
+      const normalized = file.path.split(path.sep).join("/");
+      return normalized.includes("tasks/") || normalized.includes("app/tasks/");
+    });
+    const sourceTaskPathById = new Map(
+      sourceTaskFiles.map((file) => [
+        this.resolveTaskIdentifier(file.path),
+        file.fullPath
+      ])
+    );
+    return {
+      tasks: tasks.map((task) => ({
+        identifier: task.id,
+        filePath: sourceTaskPathById.get(task.id) || task.filePath
+      }))
+    };
+  }
+  /**
+   * Converts a task source path into the runtime task identifier format.
+   *
+   * The normalization removes the task root, file extension, optional `.cron`
+   * suffix, and grouping segments, then joins remaining path segments with
+   * colons.
+   *
+   * @param {string} filePath - Task source path relative to the scanned source
+   * tree.
+   * @returns {string} Runtime task identifier derived from the file path.
+   */
+  resolveTaskIdentifier(filePath) {
+    const normalized = filePath.replace(/\\/g, "/").replace(/^(app\/)?tasks\//, "").replace(/^(.*?)(?:\.(cron))?\.(mts|mjs|ts|js)$/i, "$1").replace(/\(([^([/]+)\)\//g, "");
+    return normalized.split("/").filter((part) => part.length > 0).join(":");
+  }
+  /**
+   * Generates OpenAPI artifacts when the build enables OpenAPI output.
+   *
+   * Before generating artifacts, this method validates that reserved docs and
+   * spec routes do not collide with discovered GET routes.
+   *
+   * @param {BuildConfig} config - Build settings containing OpenAPI options.
+   * @param {Route[]} routes - Discovered route manifest entries used to build
+   * OpenAPI output.
+   * @returns {Promise<void>} Resolves after OpenAPI artifacts are generated or
+   * skipped.
+   * @throws {Error} Throws when reserved OpenAPI routes are unsafe or when the
+   * OpenAPI integration cannot be loaded.
+   */
+  async generateOpenAPIArtifactsIfEnabled(config, routes) {
+    if (!config.openapi?.enabled) return;
+    this.assertOpenAPIPathsAreSafe(routes, config.openapi);
+    const integration = await this.loadOpenAPIIntegration();
+    await integration.generateOpenAPIArtifacts({
+      outDir: config.outRoot,
+      routes,
+      config: config.openapi
+    });
+  }
+  /**
+   * Verifies that reserved OpenAPI docs and spec paths do not conflict with
+   * discovered GET routes.
+   *
+   * Lithia serves generated docs and spec assets from reserved routes when
+   * OpenAPI is enabled, so user-defined GET routes cannot reuse those paths.
+   *
+   * @param {Route[]} routes - Discovered route entries to validate.
+   * @param {OpenAPIConfig} config - OpenAPI settings that define reserved
+   * paths.
+   * @throws {Error} Throws when `docsPath` and `specPath` match or when a GET
+   * route conflicts with either reserved path.
+   */
+  assertOpenAPIPathsAreSafe(routes, config) {
+    const docsPath = normalizeReservedPath(config.docsPath);
+    const specPath = normalizeReservedPath(config.specPath);
+    if (docsPath === specPath) {
+      throw new Error(
+        "OpenAPI configuration error: docsPath and specPath must be different."
+      );
+    }
+    for (const route of routes) {
+      if (route.method && route.method.toUpperCase() !== "GET") continue;
+      const routePath = normalizeReservedPath(route.path);
+      if (routePath === docsPath || routePath === specPath) {
+        throw new Error(
+          `OpenAPI route conflict: '${route.path}' conflicts with reserved docs/spec route.`
+        );
+      }
+    }
+  }
+  /**
+   * Loads the optional `@lithia-js/openapi` integration from the current
+   * project.
+   *
+   * Resolution happens from the consumer project so the build uses the
+   * project's installed package instead of assuming the integration is
+   * available in the core package environment.
+   *
+   * @returns {Promise<{ generateOpenAPIArtifacts: (options: { outDir: string; routes: Route[]; config: OpenAPIConfig; }) => Promise<void>; }>}
+   * Module interface used to emit OpenAPI build artifacts.
+   * @throws {Error} Throws when OpenAPI is enabled but the integration package
+   * is missing or fails to load.
+   */
+  async loadOpenAPIIntegration() {
+    try {
+      const requireFromProject = createRequire(
+        path.join(process.cwd(), "package.json")
+      );
+      const resolvedPath = requireFromProject.resolve("@lithia-js/openapi");
+      return await import(pathToFileURL(resolvedPath).href);
+    } catch (error) {
+      throw new Error(
+        "OpenAPI is enabled, but '@lithia-js/openapi' is not installed or could not be loaded.",
+        { cause: error }
+      );
+    }
+  }
+};
+function normalizeReservedPath(pathname) {
+  if (!pathname) return "/";
+  const normalized = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    return normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+// src/config.ts
+var DEFAULT_CONFIG = {
+  sourceDir: "src",
+  outDir: "dist",
+  envFiles: [".env", ".env.local", ".env.development"],
+  http: {
+    port: 3e3,
+    host: "localhost",
+    maxBodySize: 1024 * 1024,
+    cors: {
+      origin: ["*"],
+      methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+      allowedHeaders: ["Content-Type", "Authorization"],
+      exposedHeaders: ["X-Powered-By"],
+      credentials: false,
+      maxAge: 86400
+    }
+  },
+  logging: {
+    requests: true,
+    events: true,
+    tasks: true
+  },
+  asyncTasks: {
+    concurrencyLimit: 10,
+    timeoutMs: 3e4
+  },
+  openapi: {
+    enabled: false,
+    docsPath: "/docs",
+    specPath: "/openapi.json",
+    title: "Lithia API",
+    version: "1.0.0"
+  }
+};
+
+// src/config/load-config.ts
+async function loadConfig() {
+  const configOptions = {
+    name: "lithia",
+    configFile: "lithia.config",
+    cwd: process.cwd(),
+    dotenv: true,
+    defaults: DEFAULT_CONFIG
+  };
+  const { config } = await loadConfig$1(configOptions);
+  return klona(config);
+}
+var AppSupervisor = class {
+  /**
+   * Creates a supervisor for the app worker lifecycle.
+   *
+   * @param {() => CreateWorkerOptions} createOptions - Factory that returns
+   * the current worker payload and environment for each spawn.
+   * @param {(event: AppToHostEvent) => Promise<void>} onInvoke - Callback that
+   * handles invocation messages forwarded from the app worker to the host.
+   * @param {string} workerBaseDir - Base directory containing the published
+   * worker entrypoints.
+   */
+  constructor(createOptions, onInvoke, workerBaseDir) {
+    this.createOptions = createOptions;
+    this.onInvoke = onInvoke;
+    this.workerBaseDir = workerBaseDir;
+  }
+  _worker = null;
+  _isReady = false;
+  _isRunning = false;
+  /**
+   * Returns the currently supervised app worker instance.
+   */
+  get worker() {
+    return this._worker;
+  }
+  /**
+   * Returns whether the current worker has reported readiness.
+   */
+  get isReady() {
+    return this._isReady;
+  }
+  /**
+   * Returns whether the supervisor currently considers the worker running.
+   */
+  get isRunning() {
+    return this._isRunning;
+  }
+  /**
+   * Starts the app worker and waits for it to report readiness.
+   *
+   * @returns {Promise<void>} Resolves after the worker emits a `ready` event.
+   * @throws {Error} Throws when worker startup fails or the worker exits before
+   * becoming ready.
+   */
+  async start() {
+    await this.spawnWorker();
+  }
+  /**
+   * Replaces the current worker with a fresh one.
+   *
+   * If a worker is already running, it is terminated before the replacement
+   * worker is spawned.
+   *
+   * @returns {Promise<void>} Resolves after the replacement worker reports
+   * readiness.
+   * @throws {Error} Throws when the replacement worker fails during startup.
+   */
+  async swap() {
+    if (this._worker && this._isRunning) {
+      await this.dispose();
+    }
+    await this.spawnWorker();
+  }
+  /**
+   * Terminates the current worker and resets supervisor state.
+   *
+   * @returns {Promise<void>} Resolves after the current worker has been
+   * terminated, or immediately when no worker is present.
+   */
+  async dispose() {
+    if (!this._worker) return;
+    const worker = this._worker;
+    this._worker = null;
+    this._isRunning = false;
+    this._isReady = false;
+    await worker.terminate();
+  }
+  /**
+   * Spawns the app worker and waits for either `ready` or a startup failure.
+   *
+   * The supervisor listens for worker lifecycle events, updates readiness and
+   * running state, forwards invocation messages to the host callback, and
+   * rejects startup when the worker reports an error or exits before becoming
+   * ready.
+   *
+   * @returns {Promise<void>} Resolves after the worker becomes ready.
+   * @throws {Error} Throws when worker construction, startup, or early exit
+   * fails.
+   */
+  async spawnWorker() {
+    logger.debug("Spawning background worker...");
+    const options = this.createOptions();
+    const worker = new Worker(
+      path.join(this.workerBaseDir, "workers", "app-worker.mjs"),
+      {
+        workerData: options.workerData,
+        env: options.env
+      }
+    );
+    this._worker = worker;
+    this._isReady = false;
+    this._isRunning = false;
+    await new Promise((resolve, reject) => {
+      let isSettled = false;
+      const resolveIfPending = () => {
+        if (isSettled) return;
+        isSettled = true;
+        resolve();
+      };
+      const rejectIfPending = (error) => {
+        if (isSettled) return;
+        isSettled = true;
+        reject(error);
+      };
+      worker.on("message", async (message) => {
+        if (message.type === "ready") {
+          this._isReady = true;
+          this._isRunning = true;
+          resolveIfPending();
+          return;
+        }
+        if (message.type === "error") {
+          logger.error("Lithia app worker reported an error:", message.error);
+          const messageText = typeof message.error === "object" && message.error !== null && "message" in message.error ? String(message.error.message) : "Lithia app worker reported an unknown startup error.";
+          rejectIfPending(new Error(messageText));
+          return;
+        }
+        await this.onInvoke(message);
+      });
+      worker.on("error", (error) => {
+        logger.error("Worker Thread crashed:", error);
+        this._isRunning = false;
+        this._isReady = false;
+        if (this._worker === worker) {
+          this._worker = null;
+        }
+        rejectIfPending(
+          error instanceof Error ? error : new Error(String(error))
+        );
+      });
+      worker.on("exit", (code) => {
+        this._isRunning = false;
+        this._isReady = false;
+        if (this._worker === worker) {
+          this._worker = null;
+        }
+        if (code !== 0) {
+          logger.debug(`App worker exited with code ${code}`);
+        }
+        rejectIfPending(
+          new Error(`App worker exited before becoming ready (code ${code}).`)
+        );
+      });
+    });
+  }
+};
+var ManifestStore = class {
+  /**
+   * Creates a manifest store backed by the current resolved host config.
+   *
+   * @param {() => LithiaOptions} getConfig - Accessor that returns the current
+   * resolved host config, including `outDir`.
+   */
+  constructor(getConfig) {
+    this.getConfig = getConfig;
+  }
+  _routes = [];
+  _events = [];
+  _tasks = [];
+  /**
+   * Returns the cached route manifest entries.
+   */
+  get routes() {
+    return this._routes;
+  }
+  /**
+   * Returns the cached event manifest entries.
+   */
+  get events() {
+    return this._events;
+  }
+  /**
+   * Returns the cached async task manifest entries.
+   */
+  get tasks() {
+    return this._tasks;
+  }
+  /**
+   * Loads the routes manifest into memory.
+   *
+   * Missing manifest files leave the current cache unchanged.
+   *
+   * @returns {Promise<void>} Resolves after the route cache has been refreshed
+   * when a manifest exists.
+   */
+  async loadRoutes() {
+    const manifest = await this.loadManifest("routes.json");
+    if (manifest) this._routes = manifest.routes;
+  }
+  /**
+   * Loads the events manifest into memory.
+   *
+   * Missing manifest files leave the current cache unchanged.
+   *
+   * @returns {Promise<void>} Resolves after the event cache has been refreshed
+   * when a manifest exists.
+   */
+  async loadEvents() {
+    const manifest = await this.loadManifest("events.json");
+    if (manifest) this._events = manifest.events;
+  }
+  /**
+   * Loads the async tasks manifest into memory.
+   *
+   * Missing manifest files leave the current cache unchanged.
+   *
+   * @returns {Promise<void>} Resolves after the task cache has been refreshed
+   * when a manifest exists.
+   */
+  async loadTasks() {
+    const manifest = await this.loadManifest("tasks.json");
+    if (manifest) this._tasks = manifest.tasks;
+  }
+  /**
+   * Loads all runtime manifests in parallel.
+   *
+   * @returns {Promise<void>} Resolves after route, event, and task manifests
+   * have been refreshed.
+   */
+  async loadAll() {
+    await Promise.all([this.loadRoutes(), this.loadEvents(), this.loadTasks()]);
+  }
+  /**
+   * Reads, parses, and validates a versioned manifest from the build output.
+   *
+   * @param {string} fileName - Manifest file name inside the configured output
+   * directory.
+   * @returns {Promise<T | null>} Parsed manifest object, or `null` when the
+   * file does not exist.
+   * @throws {Error} Throws when the manifest cannot be read or parsed.
+   * @throws {ManifestVersionMismatchError} Throws when the manifest schema
+   * version does not match the current runtime schema.
+   */
+  async loadManifest(fileName) {
+    const manifestPath = path.join(
+      process.cwd(),
+      this.getConfig().outDir,
+      fileName
+    );
+    if (!await fileExists(manifestPath)) return null;
+    const raw = await readFile(manifestPath, "utf-8").catch((error) => {
+      throw new Error(
+        `Failed to read manifest '${fileName}' from '${manifestPath}': ${error.message}`
+      );
+    });
+    let manifest;
+    try {
+      manifest = JSON.parse(raw);
+    } catch (error) {
+      throw new Error(
+        `Failed to parse manifest '${fileName}' from '${manifestPath}': ${error.message}`
+      );
+    }
+    if (manifest.version !== version) {
+      throw new ManifestVersionMismatchError(version, manifest.version);
+    }
+    return manifest;
+  }
+};
+
+// src/runtime/host/protocol.ts
+var CFG_GLOBAL_KEY = "__lithia_host_config_v1";
+var AsyncTaskRunner = class {
+  /**
+   * Creates a host-side task runner bound to the current supervisor callbacks.
+   *
+   * The runner reads config, manifests, and worker references lazily from the
+   * supplied accessors so the same instance can keep working across manifest
+   * reloads and app worker swaps.
+   *
+   * @param {TaskRunnerOptions} options - Deferred accessors and path metadata
+   * used to resolve workers, manifests, runtime config, and worker
+   * environment variables.
+   */
+  constructor(options) {
+    this.options = options;
+  }
+  runningTasks = 0;
+  invocationQueue = [];
+  syncWorkers = [];
+  /**
+   * Handles a task invocation coming from the app worker.
+   *
+   * The method enforces the global async-task concurrency limit before
+   * resolving the task manifest entry. Awaited invocations are routed through
+   * the warm worker pool so the host can post a correlated response back to the
+   * app worker, while fire-and-forget invocations always spawn a dedicated
+   * worker that owns a single execution.
+   *
+   * When the concurrency limit is already saturated, the invocation is pushed
+   * into the in-memory queue and retried only after another execution calls
+   * `finalizeInvocation()`.
+   *
+   * @param {TaskInvokeEvent} event - Invocation payload received from the app
+   * worker, including task identity, execution metadata, source, and serialized
+   * arguments.
+   * @returns {Promise<void>} Resolves after the invocation is dispatched or, if
+   * it had to wait for capacity, after the queued invocation has been retried.
+   */
+  async handleInvocation(event) {
+    const limit = this.options.getConfig().asyncTasks.concurrencyLimit;
+    if (this.runningTasks >= limit) {
+      logger.debug(
+        `[task:${event.taskId}] Concurrency limit reached, queuing invocation...`
+      );
+      return new Promise((resolve) => {
+        this.invocationQueue.push(async () => {
+          await this.handleInvocation(event);
+          resolve();
+        });
+      });
+    }
+    this.runningTasks++;
+    const taskMeta = this.options.getTasks().find((candidate) => candidate.id === event.taskId);
+    if (!taskMeta) {
+      if (!event.async) {
+        this.postSyncError(
+          event,
+          this.createErrorPayload(
+            "TaskNotFoundError",
+            `[task:${event.taskId}] Task not found in manifest.`
+          )
+        );
+      }
+      this.logTaskResult(
+        event,
+        event.taskId,
+        "error",
+        0,
+        "Task not found in manifest."
+      );
+      this.finalizeInvocation();
+      return;
+    }
+    const startedAt = performance.now();
+    if (event.async) {
+      this.executeWithDedicatedWorker(event, taskMeta, startedAt);
+      return;
+    }
+    this.executeWithWarmWorker(event, taskMeta, startedAt);
+  }
+  /**
+   * Terminates all warm workers and clears the reusable pool.
+   *
+   * This is used during host reset or shutdown to guarantee that no pooled
+   * awaited-task worker survives across runtime swaps.
+   *
+   * @returns {Promise<void>} Resolves after every currently tracked warm worker
+   * has been asked to terminate.
+   */
+  async reset() {
+    const workers = this.syncWorkers.splice(0);
+    await Promise.allSettled(workers.map((slot) => slot.worker.terminate()));
+  }
+  /**
+   * Starts a fire-and-forget invocation in its own dedicated worker.
+   *
+   * This path is used for dispatch-style task execution where the caller does
+   * not await a result. A fresh worker is created for the invocation and its
+   * full lifecycle is delegated to `attachDedicatedWorkerLifecycle()`.
+   *
+   * @param {AppInvokeAsyncEvent} event - Async dispatch metadata emitted by the
+   * app worker.
+   * @param {TaskCore} taskMeta - Manifest entry for the target task.
+   * @param {number} startedAt - High-resolution timestamp captured before
+   * dispatch begins.
+   */
+  executeWithDedicatedWorker(event, taskMeta, startedAt) {
+    const worker = this.createDedicatedWorker(taskMeta, event.args || []);
+    this.attachDedicatedWorkerLifecycle(worker, event, taskMeta, startedAt);
+  }
+  /**
+   * Executes an awaited invocation through the warm worker pool.
+   *
+   * Awaited tasks keep their worker alive for reuse after a successful
+   * invocation, but the worker is discarded if it times out, throws at the
+   * thread level, or exits unexpectedly. The host removes all listeners during
+   * cleanup and posts either a success or error response back to the app worker
+   * using the original `requestId`.
+   *
+   * @param {AppInvokeSyncEvent} event - Awaited invocation metadata emitted by
+   * the app worker.
+   * @param {TaskCore} taskMeta - Manifest entry for the target task.
+   * @param {number} startedAt - High-resolution timestamp captured before the
+   * worker receives the invocation.
+   */
+  executeWithWarmWorker(event, taskMeta, startedAt) {
+    const slot = this.acquireSyncWorker();
+    slot.busy = true;
+    const timeoutMs = this.options.getConfig().asyncTasks.timeoutMs;
+    let finalized = false;
+    const cleanup = () => {
+      if (finalized) return;
+      finalized = true;
+      clearTimeout(timer);
+      slot.busy = false;
+      slot.worker.off("message", onMessage);
+      slot.worker.off("error", onError);
+      slot.worker.off("exit", onExit);
+      this.finalizeInvocation();
+    };
+    const fail = (error, errorMessage, removeWorker = false) => {
+      if (finalized) return;
+      this.postSyncError(event, error);
+      this.logTaskResult(
+        event,
+        taskMeta.id,
+        "error",
+        performance.now() - startedAt,
+        errorMessage
+      );
+      if (removeWorker) {
+        void slot.worker.terminate();
+        this.removeSyncWorker(slot);
+      }
+      cleanup();
+    };
+    const timer = setTimeout(() => {
+      fail(
+        this.createErrorPayload(
+          "TaskTimeoutError",
+          `[task:${taskMeta.id}] Task timed out after ${timeoutMs}ms.`
+        ),
+        `Timed out after ${timeoutMs}ms.`,
+        true
+      );
+    }, timeoutMs);
+    const onMessage = (message) => {
+      if (finalized || message.executionId !== event.executionId) return;
+      if (message.type === "error") {
+        fail(message.error, message.error.message);
+        return;
+      }
+      this.postSyncSuccess(event, message.result);
+      this.logTaskResult(
+        event,
+        taskMeta.id,
+        "success",
+        performance.now() - startedAt
+      );
+      cleanup();
+    };
+    const onError = (error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      fail(
+        this.createErrorPayload("TaskExecutionError", message),
+        message,
+        true
+      );
+    };
+    const onExit = (code) => {
+      if (finalized) return;
+      fail(
+        this.createErrorPayload(
+          "TaskExecutionError",
+          `[task:${taskMeta.id}] Worker exited with code ${code}.`
+        ),
+        `Exited with code ${code}.`,
+        true
+      );
+    };
+    slot.worker.on("message", onMessage);
+    slot.worker.once("error", onError);
+    slot.worker.once("exit", onExit);
+    slot.worker.postMessage({
+      type: "invoke",
+      executionId: event.executionId,
+      task: taskMeta,
+      args: event.args || []
+    });
+  }
+  /**
+   * Attaches lifecycle handlers to a dedicated task worker.
+   *
+   * Dedicated workers are used for fire-and-forget dispatches, so the host does
+   * not need to post a result back to the app worker. Instead, it watches for
+   * completion, timeout, worker crashes, and non-zero exits, logs the terminal
+   * outcome, and schedules CRON retries when the manifest allows them.
+   *
+   * The worker is also `unref()`ed so pending detached task executions do not
+   * keep the host process alive on their own.
+   *
+   * @param {Worker} worker - Fresh one-shot worker created for a single async
+   * dispatch.
+   * @param {AppInvokeAsyncEvent} event - Fire-and-forget invocation metadata,
+   * including execution source and retry attempt.
+   * @param {TaskCore} taskMeta - Manifest entry that describes the task file and
+   * retry policy.
+   * @param {number} startedAt - High-resolution timestamp captured before
+   * worker execution starts and used for final logging.
+   */
+  attachDedicatedWorkerLifecycle(worker, event, taskMeta, startedAt) {
+    const timeoutMs = this.options.getConfig().asyncTasks.timeoutMs;
+    let isFinalized = false;
+    let completionMessageReceived = false;
+    const finalize = () => {
+      if (isFinalized) return;
+      isFinalized = true;
+      clearTimeout(timer);
+      logger.debug(`[task:${taskMeta.id}] Task finalized.`);
+      this.finalizeInvocation();
+    };
+    const timer = setTimeout(async () => {
+      if (isFinalized) return;
+      const timeoutMessage = `Timed out after ${timeoutMs}ms.`;
+      if (this.scheduleRetryIfEligible(event, taskMeta, timeoutMessage)) {
+        await worker.terminate();
+        finalize();
+        return;
+      }
+      this.logTaskResult(
+        event,
+        taskMeta.id,
+        "error",
+        performance.now() - startedAt,
+        timeoutMessage
+      );
+      await worker.terminate();
+      finalize();
+    }, timeoutMs);
+    worker.on("message", (message) => {
+      if (isFinalized) return;
+      completionMessageReceived = true;
+      if (message.type === "error") {
+        if (this.scheduleRetryIfEligible(event, taskMeta, message.error.message)) {
+          finalize();
+          return;
+        }
+        this.logTaskResult(
+          event,
+          taskMeta.id,
+          "error",
+          performance.now() - startedAt,
+          message.error.message
+        );
+        finalize();
+        return;
+      }
+      this.logTaskResult(
+        event,
+        taskMeta.id,
+        "success",
+        performance.now() - startedAt
+      );
+      finalize();
+    });
+    worker.unref();
+    worker.on("error", (error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      if (this.scheduleRetryIfEligible(event, taskMeta, message)) {
+        finalize();
+        return;
+      }
+      this.logTaskResult(
+        event,
+        taskMeta.id,
+        "error",
+        performance.now() - startedAt,
+        message
+      );
+      finalize();
+    });
+    worker.on("exit", (code) => {
+      if (isFinalized) return;
+      if (completionMessageReceived) {
+        finalize();
+        return;
+      }
+      if (code !== 0) {
+        const exitMessage = `Exited with code ${code}.`;
+        if (this.scheduleRetryIfEligible(event, taskMeta, exitMessage)) {
+          finalize();
+          return;
+        }
+        this.logTaskResult(
+          event,
+          taskMeta.id,
+          "error",
+          performance.now() - startedAt,
+          exitMessage
+        );
+      }
+      finalize();
+    });
+  }
+  /**
+   * Creates a new dedicated worker for a fire-and-forget task execution.
+   *
+   * Dedicated workers receive the task manifest entry and arguments through
+   * `workerData`, execute exactly one task, and then exit. This isolates async
+   * dispatches from pooled awaited-task workers and avoids cross-invocation
+   * listener management.
+   *
+   * @param {TaskCore} taskMeta - Manifest entry describing the task module that
+   * should run inside the worker.
+   * @param {unknown[]} args - Serialized invocation arguments forwarded to the
+   * worker entrypoint.
+   * @returns {Worker} A new worker thread configured for one-shot task
+   * execution.
+   */
+  createDedicatedWorker(taskMeta, args) {
+    return new Worker(
+      path.join(this.options.workerBaseDir, "workers", "task-worker.mjs"),
+      {
+        workerData: {
+          managedBy: "lithia",
+          environment: this.options.getEnvironment(),
+          config: this.options.getConfig(),
+          task: taskMeta,
+          args
+        },
+        env: { FORCE_COLOR: "1", ...this.options.getEnv() }
+      }
+    );
+  }
+  /**
+   * Returns an idle warm worker or creates a new one when needed.
+   *
+   * Warm workers stay alive across awaited invocations and receive work over
+   * `postMessage()`. The pool grows on demand and never shrinks automatically;
+   * failed workers are removed explicitly through `removeSyncWorker()`.
+   *
+   * @returns {SyncWorkerSlot} An idle slot ready to process an awaited
+   * invocation.
+   */
+  acquireSyncWorker() {
+    const idleWorker = this.syncWorkers.find((slot2) => !slot2.busy);
+    if (idleWorker) return idleWorker;
+    const slot = {
+      worker: new Worker(
+        path.join(this.options.workerBaseDir, "workers", "task-worker.mjs"),
+        {
+          workerData: {
+            managedBy: "lithia",
+            pooled: true,
+            environment: this.options.getEnvironment(),
+            config: this.options.getConfig()
+          },
+          env: { FORCE_COLOR: "1", ...this.options.getEnv() }
+        }
+      ),
+      busy: false
+    };
+    this.syncWorkers.push(slot);
+    return slot;
+  }
+  /**
+   * Removes a warm worker slot from the internal pool.
+   *
+   * This is used after fatal warm-worker failures such as timeouts, thread
+   * errors, or unexpected exits so future awaited invocations never reuse a
+   * broken worker instance.
+   *
+   * @param {SyncWorkerSlot} slot - Pool entry that should no longer be reused.
+   */
+  removeSyncWorker(slot) {
+    const index = this.syncWorkers.indexOf(slot);
+    if (index >= 0) {
+      this.syncWorkers.splice(index, 1);
+    }
+  }
+  /**
+   * Sends a successful awaited-task result back to the app worker.
+   *
+   * The response keeps the original `requestId` so the app worker can resolve
+   * the pending promise created for `executeTask()`.
+   *
+   * @param {AppInvokeSyncEvent} event - Awaited invocation metadata associated
+   * with the pending caller.
+   * @param {unknown} result - Serializable task return value produced by the
+   * worker.
+   */
+  postSyncSuccess(event, result) {
+    this.options.getAppWorker()?.postMessage({
+      type: "invoke_success",
+      taskId: event.taskId,
+      requestId: event.requestId,
+      result
+    });
+  }
+  /**
+   * Sends an awaited-task failure back to the app worker.
+   *
+   * The payload mirrors the protocol contract used by the app worker to reject
+   * the pending `executeTask()` request.
+   *
+   * @param {AppInvokeSyncEvent} event - Awaited invocation metadata associated
+   * with the pending caller.
+   * @param {TaskErrorPayload} error - Serializable error payload describing the
+   * task failure.
+   */
+  postSyncError(event, error) {
+    this.options.getAppWorker()?.postMessage({
+      type: "invoke_error",
+      taskId: event.taskId,
+      requestId: event.requestId,
+      error
+    });
+  }
+  /**
+   * Logs the final outcome of a task execution when task logging is enabled.
+   *
+   * Success logs include task identity and elapsed execution time. Error logs
+   * additionally include a shortened execution identifier so failures can be
+   * correlated with retries and worker-protocol messages.
+   *
+   * @param {TaskInvokeEvent} event - Invocation metadata that produced the
+   * terminal state.
+   * @param {string} taskId - Stable manifest identifier of the executed task.
+   * @param {"success" | "error"} status - Final execution status to report.
+   * @param {number} elapsed - Measured execution time in milliseconds.
+   * @param {string} [errorMessage] - Optional human-readable failure detail
+   * appended to error logs.
+   */
+  logTaskResult(event, taskId, status, elapsed, errorMessage) {
+    if (!this.options.getConfig().logging.tasks) return;
+    const statusLabel = status === "success" ? green("success") : red("error");
+    const baseMessage = status === "success" ? `[task] ${taskId} ${statusLabel} - ${elapsed.toFixed(2)}ms` : `[task] ${taskId} ${statusLabel} - ${elapsed.toFixed(2)}ms [exec:${event.executionId.slice(0, 8)}]`;
+    if (errorMessage) {
+      logger.info(baseMessage, errorMessage);
+      return;
+    }
+    logger.info(baseMessage);
+  }
+  /**
+   * Enqueues a retry for eligible CRON tasks.
+   *
+   * Retries are host-managed and only apply to CRON-triggered invocations whose
+   * manifest declares a retry budget. The retry is appended to the same
+   * invocation queue used for concurrency backpressure, so it will only run
+   * after capacity becomes available again.
+   *
+   * @param {TaskInvokeEvent} event - Failed invocation metadata.
+   * @param {TaskCore} taskMeta - Task manifest entry that provides the retry
+   * budget.
+   * @param {string} errorMessage - Failure summary included in the retry log.
+   * @returns {boolean} `true` when a retry was enqueued, or `false` when the
+   * invocation is not eligible for another attempt.
+   */
+  scheduleRetryIfEligible(event, taskMeta, errorMessage) {
+    const maxRetries = taskMeta.retries ?? 0;
+    const currentAttempt = event.attempt ?? 0;
+    if (event.source !== "CRON" || currentAttempt >= maxRetries) {
+      return false;
+    }
+    const nextAttempt = currentAttempt + 1;
+    logger.warn(
+      `[task:${taskMeta.id}][exec:${event.executionId.slice(0, 8)}] CRON retry ${nextAttempt}/${maxRetries}`,
+      errorMessage
+    );
+    this.invocationQueue.push(async () => {
+      await this.handleInvocation({
+        ...event,
+        attempt: nextAttempt
+      });
+    });
+    return true;
+  }
+  /**
+   * Creates a serializable task error payload.
+   *
+   * The host uses this helper when it needs to synthesize failures that do not
+   * originate inside the task worker itself, such as missing manifest entries,
+   * host-observed timeouts, or abrupt worker exits.
+   *
+   * @param {string} name - Stable error name to expose through the host-worker
+   * protocol.
+   * @param {string} message - Human-readable failure message.
+   * @param {unknown} [cause] - Optional original cause when a serializable value
+   * is available.
+   * @returns {TaskErrorPayload} Serializable error payload ready to be posted to
+   * the app worker or written to logs.
+   */
+  createErrorPayload(name, message, cause) {
+    return {
+      name,
+      message,
+      cause
+    };
+  }
+  /**
+   * Marks a task execution as complete and drains the next queued invocation.
+   *
+   * Every terminal path must call this exactly once after it has released any
+   * worker-specific resources. The method decrements the global running-task
+   * counter and immediately starts the next queued invocation, if one exists.
+   */
+  finalizeInvocation() {
+    this.runningTasks--;
+    const next = this.invocationQueue.shift();
+    if (next) next();
+  }
+};
+
+// src/runtime/host/host-supervisor.ts
+sms.install({
+  environment: "node",
+  handleUncaughtExceptions: false
+});
+var HostSupervisor = class {
+  /**
+   * Creates the main-process supervisor for a Lithia runtime instance.
+   *
+   * The supervisor owns configuration loading, environment snapshots, build
+   * orchestration, manifest loading, app worker lifecycle, and async task
+   * execution coordination.
+   *
+   * @param {LithiaOpts} opts - Minimal host runtime options.
+   * @throws {Error} Throws when instantiated outside the Node.js main thread.
+   */
+  constructor(opts) {
+    this.opts = opts;
+    if (!isMainThread) {
+      throw new Error(
+        "HostSupervisor must be instantiated in the Main Thread."
+      );
+    }
+    this._builder = new BuildOrchestrator();
+    this._manifestStore = new ManifestStore(() => this.config);
+    this._appSupervisor = new AppSupervisor(
+      () => ({
+        workerData: {
+          managedBy: "lithia",
+          environment: this.environment,
+          config: this.config,
+          routes: this.routes,
+          events: this.events,
+          tasks: this.tasks,
+          isFirstApp: ++this._appCount === 1 || this._lastPortUsed !== this.config.http.port
+        },
+        env: { FORCE_COLOR: "1", ...this._env }
+      }),
+      (event) => this.handleAppMessage(event),
+      import.meta.dirname
+    );
+    this._taskRunner = new AsyncTaskRunner({
+      getConfig: () => this.config,
+      getEnvironment: () => this.environment,
+      getTasks: () => this.tasks,
+      getAppWorker: () => this._appSupervisor.worker,
+      getEnv: () => this._env,
+      workerBaseDir: import.meta.dirname
+    });
+  }
+  _config;
+  _env = {};
+  _builder;
+  _manifestStore;
+  _appSupervisor;
+  _taskRunner;
+  _appCount = 0;
+  _lastPortUsed = 0;
+  /**
+   * Returns the resolved runtime configuration for the current host lifecycle.
+   *
+   * In production, the config is read from the global host runtime slot
+   * exposed through `CFG_GLOBAL_KEY`. In other environments, the in-memory
+   * loaded config snapshot is returned.
+   */
+  get config() {
+    return this.environment === "production" ? globalThis[CFG_GLOBAL_KEY] : this._config;
+  }
+  /**
+   * Returns the environment mode assigned to this host instance.
+   */
+  get environment() {
+    return this.opts.environment;
+  }
+  /**
+   * Returns whether the supervised app worker has reported readiness.
+   */
+  get isAppReady() {
+    return this._appSupervisor.isReady;
+  }
+  /**
+   * Returns the currently loaded route manifest entries.
+   */
+  get routes() {
+    return this._manifestStore.routes;
+  }
+  /**
+   * Returns the currently loaded event manifest entries.
+   */
+  get events() {
+    return this._manifestStore.events;
+  }
+  /**
+   * Returns the currently loaded async task manifest entries.
+   */
+  get tasks() {
+    return this._manifestStore.tasks;
+  }
+  /**
+   * Loads the user configuration file into the host runtime.
+   *
+   * This is skipped in production, where config is expected to be available
+   * through the global runtime slot.
+   *
+   * @returns {Promise<void>} Resolves after the config snapshot has been
+   * loaded when applicable.
+   */
+  async loadConfig() {
+    if (this.environment === "production") return;
+    this._config = await loadConfig();
+    this._lastPortUsed = this._config.http.port;
+  }
+  /**
+   * Loads and merges configured environment files into the host snapshot.
+   *
+   * Files are loaded in config order, and later files override earlier keys.
+   * Only files that currently exist are considered.
+   *
+   * @returns {Promise<Record<string, string>>} Copy of the merged environment
+   * snapshot.
+   * @throws {LithiaError} Throws when configuration has not been loaded yet.
+   */
+  async loadEnv() {
+    this.ensureConfigLoaded();
+    const cwd = process.cwd();
+    const envFiles = await this.getAvailableEnvFiles();
+    const nextEnv = {};
+    for (const file of envFiles) {
+      try {
+        const raw = await readFile(path.join(cwd, file), "utf-8");
+        const parsed = parseEnv(raw);
+        Object.assign(nextEnv, parsed);
+      } catch {
+        logger.warn(`Failed to parse env file: ${file}`);
+      }
+    }
+    this._env = nextEnv;
+    return { ...this._env };
+  }
+  /**
+   * Loads the routes manifest from the current build output.
+   *
+   * @returns {Promise<void>} Resolves after the route manifest cache has been
+   * refreshed.
+   */
+  async loadRoutes() {
+    await this._manifestStore.loadRoutes();
+  }
+  /**
+   * Loads the events manifest from the current build output.
+   *
+   * @returns {Promise<void>} Resolves after the event manifest cache has been
+   * refreshed.
+   */
+  async loadEvents() {
+    await this._manifestStore.loadEvents();
+  }
+  /**
+   * Loads the async tasks manifest from the current build output.
+   *
+   * @returns {Promise<void>} Resolves after the task manifest cache has been
+   * refreshed.
+   */
+  async loadTasks() {
+    await this._manifestStore.loadTasks();
+  }
+  /**
+   * Returns a copy of the currently loaded environment snapshot.
+   *
+   * @returns {Record<string, string>} Shallow copy of the host environment
+   * snapshot.
+   */
+  getEnvSnapshot() {
+    return { ...this._env };
+  }
+  /**
+   * Replaces the in-memory resolved config snapshot.
+   *
+   * @param {LithiaOptions} config - Config snapshot that should replace the
+   * current in-memory value.
+   */
+  replaceConfig(config) {
+    this._config = config;
+  }
+  /**
+   * Replaces the in-memory environment snapshot.
+   *
+   * @param {Record<string, string>} env - Environment snapshot that should
+   * replace the current in-memory value.
+   */
+  replaceEnv(env) {
+    this._env = { ...env };
+  }
+  /**
+   * Builds the application output and manifests.
+   *
+   * Returns `true` when the build succeeds. In non-build environments, failures
+   * are reported and surfaced as `false` so the caller can decide how to
+   * recover.
+   *
+   * @returns {Promise<boolean>} `true` when the build succeeds, otherwise
+   * `false` outside build mode.
+   * @throws {unknown} Rethrows build failures when the host runs in `build`
+   * mode.
+   */
+  async build() {
+    this.ensureConfigLoaded();
+    const startTime = performance.now();
+    try {
+      await this._builder.build({
+        sourceDir: this.config.sourceDir,
+        outRoot: this.config.outDir,
+        openapi: this.config.openapi
+      });
+      const duration = performance.now() - startTime;
+      logger.success(`Compiled successfully in ${duration.toFixed(2)}ms.`);
+      return true;
+    } catch (error) {
+      logger.error(`Build failed: ${error.message}`);
+      if (this.environment === "build") throw error;
+      return false;
+    }
+  }
+  /**
+   * Loads config/env and prints the CLI header for the current run.
+   *
+   * @returns {Promise<void>} Resolves after config, env, and header output are
+   * ready.
+   */
+  async setup() {
+    await this.loadConfig();
+    await this.loadEnv();
+    await this.printHeader();
+  }
+  /**
+   * Starts the app worker using the latest manifests and runtime state.
+   *
+   * @returns {Promise<void>} Resolves after manifests are loaded and the app
+   * worker reports readiness.
+   * @throws {Error} Throws when worker startup fails.
+   */
+  async start() {
+    if (!this._config) await this.loadConfig();
+    await this._manifestStore.loadAll();
+    await this._appSupervisor.start();
+    logger.debug(`Instance started in ${this.environment} mode.`);
+  }
+  /**
+   * Reloads manifests, resets task workers, and swaps the app worker.
+   *
+   * @returns {Promise<void>} Resolves after manifests are refreshed, task
+   * workers are reset, and the replacement app worker becomes ready.
+   */
+  async reload() {
+    await this._manifestStore.loadAll();
+    await this._taskRunner.reset();
+    await this.swapApp();
+  }
+  /**
+   * Stops task execution and tears down the app worker.
+   *
+   * @returns {Promise<void>} Resolves after warm task workers and the app
+   * worker have been terminated.
+   */
+  async stop() {
+    await this._taskRunner.reset();
+    await this._appSupervisor.dispose();
+    logger.debug("Lithia instance stopped.");
+  }
+  /**
+   * Replaces the current app worker with a fresh instance.
+   *
+   * @returns {Promise<void>} Resolves after the replacement app worker reports
+   * readiness.
+   */
+  async swapApp() {
+    await this._appSupervisor.swap();
+  }
+  /**
+   * Prints the Lithia CLI header and the env files currently in use.
+   *
+   * @returns {Promise<void>} Resolves after header output has been printed.
+   */
+  async printHeader() {
+    const files = await this.getAvailableEnvFiles();
+    logger.event(green(`Lithia.js ${version}`));
+    if (files.length) logger.info(`Environment: ${files.join(", ")}`);
+    console.log();
+  }
+  /**
+   * Prints the loaded routes in a CLI-friendly tree format.
+   */
+  printRouteTree() {
+    this.printTree(
+      "Routes",
+      this.routes,
+      (route) => `${(route.method || "all").toUpperCase()} ${route.path}`,
+      (route) => route.dynamic ? "\u0192" : "\u25CB"
+    );
+  }
+  /**
+   * Prints the loaded events in a CLI-friendly tree format.
+   */
+  printEventTree() {
+    this.printTree(
+      "Events",
+      this.events,
+      (event) => event.name,
+      () => "\u03BB"
+    );
+  }
+  /**
+   * Prints the loaded async tasks in a CLI-friendly tree format.
+   */
+  printTaskTree() {
+    this.printTree(
+      "Async Tasks",
+      this.tasks,
+      (task) => task.id,
+      (task) => task.trigger === "CRON" ? "\u29D6" : "\u2699"
+    );
+  }
+  /**
+   * Forwards task invocation messages emitted by the app worker to the async
+   * task runner.
+   *
+   * @param {AppToHostEvent} event - Message emitted by the app worker.
+   * @returns {Promise<void>} Resolves after invocation messages are handled or
+   * ignored.
+   */
+  async handleAppMessage(event) {
+    if (event.type !== "invoke") return;
+    await this._taskRunner.handleInvocation(event);
+  }
+  /**
+   * Prints a simple labeled tree for CLI inspection of loaded runtime state.
+   *
+   * @param {string} label - Section label printed above the tree.
+   * @param {T[]} items - Items to render.
+   * @param {(item: T) => string} nameFn - Formatter used for the item label.
+   * @param {(item: T) => string} symbolFn - Formatter used for the item
+   * prefix symbol.
+   */
+  printTree(label, items, nameFn, symbolFn) {
+    if (items.length === 0) return;
+    console.log(`
+\x1B[4m${label}:\x1B[0m`);
+    items.forEach((item, index) => {
+      const branch = index === items.length - 1 ? "\u2514" : "\u251C";
+      console.log(`${branch} ${symbolFn(item)} ${nameFn(item)}`);
+    });
+  }
+  /**
+   * Returns the configured env files that currently exist on disk.
+   *
+   * @returns {Promise<string[]>} Existing env files in configured load order.
+   */
+  async getAvailableEnvFiles() {
+    const existing = [];
+    for (const file of this.config.envFiles) {
+      if (await fileExists(path.join(process.cwd(), file))) existing.push(file);
+    }
+    return existing;
+  }
+  /**
+   * Verifies that a config snapshot is available before host operations that
+   * depend on it.
+   *
+   * @throws {LithiaError} Throws when configuration has not been loaded.
+   */
+  ensureConfigLoaded() {
+    if (!this.config) throw new LithiaError("Configuration not loaded.");
+  }
+};
+
+export { CFG_GLOBAL_KEY, HostSupervisor, NotInLithiaContextError, RouteNotFoundError };
+//# sourceMappingURL=_index.mjs.map
+//# sourceMappingURL=_index.mjs.map