@lithia-js/core 1.0.0-canary.20 → 1.0.0-canary.22

package/dist/_index.d.ts

@@ -1,6 +1,6 @@
-import { L as LithiaError, a as LithiaOptions, R as Route, E as Event } from './protocol-Ddx-dP-_.js';
-export { C as CFG_GLOBAL_KEY, b as RouteNotFoundError } from './protocol-Ddx-dP-_.js';
-import { T as TaskCore } from './tasks-qNCrAmuM.js';
+import { L as LithiaError, a as LithiaOptions, R as Route, E as Event } from './protocol-BGSauS_S.js';
+export { C as CFG_GLOBAL_KEY, b as RouteNotFoundError } from './protocol-BGSauS_S.js';
+import { T as TaskCore } from './tasks-X-3clDS8.js';
 import '@lithia-js/utils';
 import 'c12';
 
@@ -18,6 +18,9 @@ declare class NotInLithiaContextError extends LithiaError {
  * Minimal runtime options required to bootstrap the Lithia host.
  */
 interface LithiaOpts {
+    /**
+     * Runtime environment mode used to load config, manifests, and workers.
+     */
     environment: Environment;
 }
 /**
@@ -36,43 +39,106 @@ declare class HostSupervisor {
     private readonly _taskRunner;
     private _appCount;
     private _lastPortUsed;
+    /**
+     * 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: LithiaOpts);
+    /**
+     * 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(): LithiaOptions;
+    /**
+     * Returns the environment mode assigned to this host instance.
+     */
     get environment(): Environment;
+    /**
+     * Returns whether the supervised app worker has reported readiness.
+     */
     get isAppReady(): boolean;
+    /**
+     * Returns the currently loaded route manifest entries.
+     */
     get routes(): Route[];
+    /**
+     * Returns the currently loaded event manifest entries.
+     */
     get events(): Event[];
+    /**
+     * Returns the currently loaded async task manifest entries.
+     */
     get tasks(): TaskCore[];
     /**
      * 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.
      */
     loadConfig(): Promise<void>;
     /**
      * 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.
      */
     loadEnv(): Promise<Record<string, string>>;
     /**
      * Loads the routes manifest from the current build output.
+     *
+     * @returns {Promise<void>} Resolves after the route manifest cache has been
+     * refreshed.
      */
     loadRoutes(): Promise<void>;
     /**
      * Loads the events manifest from the current build output.
+     *
+     * @returns {Promise<void>} Resolves after the event manifest cache has been
+     * refreshed.
      */
     loadEvents(): Promise<void>;
     /**
      * Loads the async tasks manifest from the current build output.
+     *
+     * @returns {Promise<void>} Resolves after the task manifest cache has been
+     * refreshed.
      */
     loadTasks(): Promise<void>;
     /**
      * Returns a copy of the currently loaded environment snapshot.
+     *
+     * @returns {Record<string, string>} Shallow copy of the host environment
+     * snapshot.
      */
     getEnvSnapshot(): Record<string, string>;
     /**
      * Replaces the in-memory resolved config snapshot.
+     *
+     * @param {LithiaOptions} config - Config snapshot that should replace the
+     * current in-memory value.
      */
     replaceConfig(config: LithiaOptions): void;
     /**
      * Replaces the in-memory environment snapshot.
+     *
+     * @param {Record<string, string>} env - Environment snapshot that should
+     * replace the current in-memory value.
      */
     replaceEnv(env: Record<string, string>): void;
     /**
@@ -81,30 +147,53 @@ declare class HostSupervisor {
      * 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.
      */
     build(): Promise<boolean>;
     /**
      * Loads config/env and prints the CLI header for the current run.
+     *
+     * @returns {Promise<void>} Resolves after config, env, and header output are
+     * ready.
      */
     setup(): Promise<void>;
     /**
      * 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.
      */
     start(): Promise<void>;
     /**
      * 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.
      */
     reload(): Promise<void>;
     /**
      * Stops task execution and tears down the app worker.
+     *
+     * @returns {Promise<void>} Resolves after warm task workers and the app
+     * worker have been terminated.
      */
     stop(): Promise<void>;
     /**
      * Replaces the current app worker with a fresh instance.
+     *
+     * @returns {Promise<void>} Resolves after the replacement app worker reports
+     * readiness.
      */
     swapApp(): Promise<void>;
     /**
      * Prints the Lithia CLI header and the env files currently in use.
+     *
+     * @returns {Promise<void>} Resolves after header output has been printed.
      */
     printHeader(): Promise<void>;
     /**
@@ -119,9 +208,37 @@ declare class HostSupervisor {
      * Prints the loaded async tasks in a CLI-friendly tree format.
      */
     printTaskTree(): void;
+    /**
+     * 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.
+     */
     private handleAppMessage;
+    /**
+     * 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.
+     */
     private printTree;
+    /**
+     * Returns the configured env files that currently exist on disk.
+     *
+     * @returns {Promise<string[]>} Existing env files in configured load order.
+     */
     private getAvailableEnvFiles;
+    /**
+     * Verifies that a config snapshot is available before host operations that
+     * depend on it.
+     *
+     * @throws {LithiaError} Throws when configuration has not been loaded.
+     */
     private ensureConfigLoaded;
 }