@zudojs/plugins 1.3.2 → 1.4.0

package/dist/index.d.ts

@@ -56,11 +56,10 @@ export type { LifecycleControllerOptions } from "./pluginLifecycle/pluginLifecyc
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvents/pluginEvent.core.js";
 export type { PluginLifecycleEvent } from "./pluginEvents/pluginEvent.core.js";
 export { isPluginEventBus, toPluginEvents, } from "./pluginEvents/pluginEvent.bus.js";
-export { buildDiagnosticReport, createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
+export { buildDiagnosticReport, resolvePluginHealth, createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
 export type { PluginHealth, PluginHealthStatus, PluginDiagnostic, PluginDiagnosticReport, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
 export { isValidTransition, VALID_STATE_TRANSITIONS, } from "./pluginTypes/pluginState.type.js";
 export { createPluginContext, createOwnedPluginContext, } from "./pluginIntegration/pluginContext.core.js";
 export type { CreatePluginContextOptions, OwnedPluginContext, } from "./pluginIntegration/pluginContext.core.js";
 export { PluginError, PluginRegistrationError, PluginAlreadyRegisteredError, PluginNotFoundError, PluginDependencyError, PluginDependencyCycleError, PluginInitializationError, PluginStartError, PluginStopError, PluginDisposeError, PluginTimeoutError, PluginStateError, createPluginError, isPluginError, } from "@zudojs/errors";
 export type { PluginState, PluginMetadata, PluginDependency, PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginEventBus, PluginEventSource, PluginDisposable, Plugin, PluginErrorOptions, } from "./pluginTypes/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -50,8 +50,7 @@ export { PluginDependencyVersionError } from "./pluginDependencies/versionCheck.
 export { LifecycleController } from "./pluginLifecycle/pluginLifecycle.core.js";
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvents/pluginEvent.core.js";
 export { isPluginEventBus, toPluginEvents, } from "./pluginEvents/pluginEvent.bus.js";
-export { buildDiagnosticReport, createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
+export { buildDiagnosticReport, resolvePluginHealth, createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
 export { isValidTransition, VALID_STATE_TRANSITIONS, } from "./pluginTypes/pluginState.type.js";
 export { createPluginContext, createOwnedPluginContext, } from "./pluginIntegration/pluginContext.core.js";
 export { PluginError, PluginRegistrationError, PluginAlreadyRegisteredError, PluginNotFoundError, PluginDependencyError, PluginDependencyCycleError, PluginInitializationError, PluginStartError, PluginStopError, PluginDisposeError, PluginTimeoutError, PluginStateError, createPluginError, isPluginError, } from "@zudojs/errors";
-//# sourceMappingURL=index.js.map

package/dist/pluginDependencies/dependencyResolver.core.d.ts

@@ -67,4 +67,3 @@ export declare class DependencyResolver {
  * and the dependency itself, so a startup failure says who needed what.
  */
 export declare function assertResolutionValid(resolution: DependencyResolution): void;
-//# sourceMappingURL=dependencyResolver.core.d.ts.map

package/dist/pluginDependencies/dependencyResolver.core.js

@@ -148,4 +148,3 @@ export function assertResolutionValid(resolution) {
         throw new PluginDependencyCycleError(resolution.cycles[0].split(" -> "));
     }
 }
-//# sourceMappingURL=dependencyResolver.core.js.map

package/dist/pluginDependencies/index.d.ts

@@ -9,4 +9,3 @@ export { DependencyResolver, assertResolutionValid, } from "./dependencyResolver
 export type { SemVer } from "./versionCheck.core.js";
 export { PluginDependencyVersionError } from "./versionCheck.core.js";
 export { parseVersion, compareVersions, satisfiesVersion, assertDependencyVersions, } from "./versionCheck.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/pluginDependencies/index.js

@@ -7,4 +7,3 @@
 export { DependencyResolver, assertResolutionValid, } from "./dependencyResolver.core.js";
 export { PluginDependencyVersionError } from "./versionCheck.core.js";
 export { parseVersion, compareVersions, satisfiesVersion, assertDependencyVersions, } from "./versionCheck.core.js";
-//# sourceMappingURL=index.js.map

package/dist/pluginDependencies/versionCheck.core.d.ts

@@ -64,4 +64,3 @@ export declare function satisfiesVersion(version: string, range: string): boolea
  * @throws {PluginDependencyError} on the first unsatisfied constraint.
  */
 export declare function assertDependencyVersions(plugins: ReadonlyMap<string, Plugin>): void;
-//# sourceMappingURL=versionCheck.core.d.ts.map

package/dist/pluginDependencies/versionCheck.core.js

@@ -196,4 +196,3 @@ export function assertDependencyVersions(plugins) {
         }
     }
 }
-//# sourceMappingURL=versionCheck.core.js.map

package/dist/pluginDiagnostics/index.d.ts

@@ -4,5 +4,4 @@
  * Plugin health checks and diagnostic reporting.
  */
 export type { PluginHealthStatus, PluginHealth, PluginDiagnostic, PluginDiagnosticReport, } from "./pluginDiagnostic.core.js";
-export { createHealthyHealth, createDegradedHealth, createUnhealthyHealth, buildDiagnosticReport, } from "./pluginDiagnostic.core.js";
-//# sourceMappingURL=index.d.ts.map
+export { createHealthyHealth, createDegradedHealth, createUnhealthyHealth, buildDiagnosticReport, resolvePluginHealth, } from "./pluginDiagnostic.core.js";

package/dist/pluginDiagnostics/index.js

@@ -3,5 +3,4 @@
  *
  * Plugin health checks and diagnostic reporting.
  */
-export { createHealthyHealth, createDegradedHealth, createUnhealthyHealth, buildDiagnosticReport, } from "./pluginDiagnostic.core.js";
-//# sourceMappingURL=index.js.map
+export { createHealthyHealth, createDegradedHealth, createUnhealthyHealth, buildDiagnosticReport, resolvePluginHealth, } from "./pluginDiagnostic.core.js";

package/dist/pluginDiagnostics/pluginDiagnostic.core.d.ts

@@ -1,17 +1,10 @@
 import type { Plugin } from "../pluginTypes/plugin.type.js";
+import type { PluginHealth, PluginHealthStatus } from "../pluginTypes/plugin.type.js";
 import type { PluginMetadata } from "../pluginTypes/pluginMetadata.type.js";
 import type { PluginState } from "../pluginTypes/pluginState.type.js";
-/**
- * Plugin health status.
- */
-export type PluginHealthStatus = "healthy" | "degraded" | "unhealthy";
-/**
- * Plugin health information.
- */
-export interface PluginHealth {
-    readonly status: PluginHealthStatus;
-    readonly details?: unknown;
-}
+import { createDegradedHealth, createHealthyHealth, createUnhealthyHealth, resolvePluginHealth } from "./pluginDiagnostic.health.js";
+export type { PluginHealth, PluginHealthStatus };
+export { createDegradedHealth, createHealthyHealth, createUnhealthyHealth, resolvePluginHealth, };
 /**
  * Individual plugin diagnostic information.
  */
@@ -35,18 +28,6 @@ export interface PluginDiagnosticReport {
     readonly unhealthy: number;
     readonly failed: number;
 }
-/**
- * Creates a default healthy status for a plugin.
- */
-export declare function createHealthyHealth(): PluginHealth;
-/**
- * Creates a degraded health status for a plugin.
- */
-export declare function createDegradedHealth(details?: unknown): PluginHealth;
-/**
- * Creates an unhealthy health status for a plugin.
- */
-export declare function createUnhealthyHealth(details?: unknown): PluginHealth;
 /**
  * Builds a diagnostic report from registered plugins.
  */
@@ -61,4 +42,3 @@ export declare function buildDiagnosticReport(plugins: Array<{
     readonly failed?: boolean;
     readonly error?: unknown;
 }>): PluginDiagnosticReport;
-//# sourceMappingURL=pluginDiagnostic.core.d.ts.map

package/dist/pluginDiagnostics/pluginDiagnostic.core.js

@@ -1,21 +1,5 @@
-/**
- * Creates a default healthy status for a plugin.
- */
-export function createHealthyHealth() {
-    return { status: "healthy" };
-}
-/**
- * Creates a degraded health status for a plugin.
- */
-export function createDegradedHealth(details) {
-    return { status: "degraded", ...(details !== undefined ? { details } : {}) };
-}
-/**
- * Creates an unhealthy health status for a plugin.
- */
-export function createUnhealthyHealth(details) {
-    return { status: "unhealthy", ...(details !== undefined ? { details } : {}) };
-}
+import { createDegradedHealth, createHealthyHealth, createUnhealthyHealth, resolvePluginHealth, } from "./pluginDiagnostic.health.js";
+export { createDegradedHealth, createHealthyHealth, createUnhealthyHealth, resolvePluginHealth, };
 /**
  * Builds a diagnostic report from registered plugins.
  */
@@ -26,11 +10,7 @@ export function buildDiagnosticReport(plugins) {
             plugin: plugin.metadata,
             state,
             failed: hasFailed,
-            health: hasFailed
-                ? createUnhealthyHealth(error instanceof Error ? error.message : error)
-                : state === "started"
-                    ? createHealthyHealth()
-                    : createDegradedHealth(),
+            health: resolvePluginHealth(plugin, state, hasFailed, error),
             dependencies: plugin.dependencies?.map((d) => d.name) ?? [],
             optionalDependencies: plugin.optionalDependencies?.map((d) => d.name) ?? [],
         };
@@ -48,4 +28,3 @@ export function buildDiagnosticReport(plugins) {
         failed,
     };
 }
-//# sourceMappingURL=pluginDiagnostic.core.js.map

package/dist/pluginDiagnostics/pluginDiagnostic.health.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Health resolution for one plugin, from its lifecycle state and its own
+ * `health()` hook.
+ *
+ * @module pluginDiagnostics/pluginDiagnostic.health
+ */
+import type { Plugin } from "../pluginTypes/plugin.type.js";
+import type { PluginHealth } from "../pluginTypes/plugin.type.js";
+import type { PluginState } from "../pluginTypes/pluginState.type.js";
+/**
+ * Creates a default healthy status for a plugin.
+ */
+export declare function createHealthyHealth(): PluginHealth;
+/**
+ * Creates a degraded health status for a plugin.
+ */
+export declare function createDegradedHealth(details?: unknown): PluginHealth;
+/**
+ * Creates an unhealthy health status for a plugin.
+ */
+export declare function createUnhealthyHealth(details?: unknown): PluginHealth;
+/**
+ * Health of one plugin.
+ *
+ * A failed plugin is `unhealthy`. A started plugin answers with its own
+ * `health()` when it has one (a throwing `health()` is `unhealthy`), else
+ * `healthy`. A plugin part-way through boot or a transition is `degraded`.
+ * A plugin that is idle — `registered`, or cleanly `stopped` or `disposed`
+ * — is `healthy`: before this rule every plugin read `degraded` after a
+ * clean `stop()`, which made the report useless during shutdown.
+ */
+export declare function resolvePluginHealth(plugin: Plugin, state: PluginState, failed: boolean, error?: unknown): PluginHealth;

package/dist/pluginDiagnostics/pluginDiagnostic.health.js

@@ -0,0 +1,65 @@
+/**
+ * Health resolution for one plugin, from its lifecycle state and its own
+ * `health()` hook.
+ *
+ * @module pluginDiagnostics/pluginDiagnostic.health
+ */
+/**
+ * States in which a plugin is between two settled states, or brought
+ * part-way up by a `start()` that has not finished.
+ */
+const IN_PROGRESS_STATES = new Set([
+    "installing",
+    "installed",
+    "initializing",
+    "initialized",
+    "starting",
+    "stopping",
+    "disposing",
+]);
+/**
+ * Creates a default healthy status for a plugin.
+ */
+export function createHealthyHealth() {
+    return { status: "healthy" };
+}
+/**
+ * Creates a degraded health status for a plugin.
+ */
+export function createDegradedHealth(details) {
+    return { status: "degraded", ...(details !== undefined ? { details } : {}) };
+}
+/**
+ * Creates an unhealthy health status for a plugin.
+ */
+export function createUnhealthyHealth(details) {
+    return { status: "unhealthy", ...(details !== undefined ? { details } : {}) };
+}
+/**
+ * Health of one plugin.
+ *
+ * A failed plugin is `unhealthy`. A started plugin answers with its own
+ * `health()` when it has one (a throwing `health()` is `unhealthy`), else
+ * `healthy`. A plugin part-way through boot or a transition is `degraded`.
+ * A plugin that is idle — `registered`, or cleanly `stopped` or `disposed`
+ * — is `healthy`: before this rule every plugin read `degraded` after a
+ * clean `stop()`, which made the report useless during shutdown.
+ */
+export function resolvePluginHealth(plugin, state, failed, error) {
+    if (failed) {
+        return createUnhealthyHealth(error instanceof Error ? error.message : error);
+    }
+    if (state === "started") {
+        if (typeof plugin.health !== "function")
+            return createHealthyHealth();
+        try {
+            return plugin.health();
+        }
+        catch (cause) {
+            return createUnhealthyHealth(cause instanceof Error ? cause.message : cause);
+        }
+    }
+    return IN_PROGRESS_STATES.has(state)
+        ? createDegradedHealth({ state })
+        : createHealthyHealth();
+}

package/dist/pluginEvents/index.d.ts

@@ -7,4 +7,3 @@ export type { PluginLifecycleEvent } from "./pluginEvent.core.js";
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvent.core.js";
 export { isPluginEventBus, toPluginEvents } from "./pluginEvent.bus.js";
 export { deliverPluginEvent } from "./pluginEvent.deliver.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/pluginEvents/index.js

@@ -6,4 +6,3 @@
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvent.core.js";
 export { isPluginEventBus, toPluginEvents } from "./pluginEvent.bus.js";
 export { deliverPluginEvent } from "./pluginEvent.deliver.js";
-//# sourceMappingURL=index.js.map

package/dist/pluginEvents/pluginEvent.bus.d.ts

@@ -23,4 +23,3 @@ export declare function isPluginEventBus(source: PluginEventSource): source is P
  * @returns A {@link PluginEvents} view of it.
  */
 export declare function toPluginEvents(source: PluginEventSource): PluginEvents;
-//# sourceMappingURL=pluginEvent.bus.d.ts.map

package/dist/pluginEvents/pluginEvent.bus.js

@@ -53,4 +53,3 @@ export function toPluginEvents(source) {
         },
     };
 }
-//# sourceMappingURL=pluginEvent.bus.js.map

package/dist/pluginEvents/pluginEvent.core.d.ts

@@ -31,4 +31,3 @@ export declare const PLUGIN_EVENTS: {
  * Creates a plugin lifecycle event.
  */
 export declare function createPluginLifecycleEvent(plugin: PluginMetadata, state: PluginState, previousState?: PluginState, error?: unknown): PluginLifecycleEvent;
-//# sourceMappingURL=pluginEvent.core.d.ts.map

package/dist/pluginEvents/pluginEvent.core.js

@@ -27,4 +27,3 @@ export function createPluginLifecycleEvent(plugin, state, previousState, error)
         ...(error !== undefined ? { error } : {}),
     };
 }
-//# sourceMappingURL=pluginEvent.core.js.map

package/dist/pluginEvents/pluginEvent.deliver.d.ts

@@ -15,4 +15,3 @@ import type { PluginEvents } from "../pluginTypes/pluginContext.type.js";
  * @param onFailure - Receives a synchronous throw or an async rejection.
  */
 export declare function deliverPluginEvent(events: PluginEvents, name: string, payload: unknown, onFailure: (error: unknown) => void): void;
-//# sourceMappingURL=pluginEvent.deliver.d.ts.map

package/dist/pluginEvents/pluginEvent.deliver.js

@@ -38,4 +38,3 @@ function isThenable(value) {
         (typeof value === "object" || typeof value === "function") &&
         typeof value.then === "function");
 }
-//# sourceMappingURL=pluginEvent.deliver.js.map

package/dist/pluginIntegration/index.d.ts

@@ -6,4 +6,3 @@
 export type { CreatePluginContextOptions, OwnedPluginContext, } from "./pluginContext.core.js";
 export { createPluginContext, createOwnedPluginContext, } from "./pluginContext.core.js";
 export type { PluginContext } from "../pluginTypes/pluginContext.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/pluginIntegration/index.js

@@ -4,4 +4,3 @@
  * Plugin context factory and integration helpers.
  */
 export { createPluginContext, createOwnedPluginContext, } from "./pluginContext.core.js";
-//# sourceMappingURL=index.js.map

package/dist/pluginIntegration/pluginContext.core.d.ts

@@ -24,6 +24,12 @@ export interface CreatePluginContextOptions {
      * one it aborts on shutdown so plugins are told to stop.
      */
     readonly abortController?: AbortController;
+    /**
+     * Metadata of the host application, exposed to the plugin as
+     * `context.host`. The manager fills it from the `plugin` metadata of
+     * the context passed to `start()`/`stop()`.
+     */
+    readonly host?: PluginMetadata;
 }
 /**
  * A plugin context together with the handles needed to tear it down.
@@ -51,4 +57,3 @@ export declare function createOwnedPluginContext(plugin: PluginMetadata, options
  * collection and the abort handle with the context.
  */
 export declare function createPluginContext(plugin: PluginMetadata, options?: CreatePluginContextOptions): PluginContext;
-//# sourceMappingURL=pluginContext.core.d.ts.map

package/dist/pluginIntegration/pluginContext.core.js

@@ -11,6 +11,7 @@ export function createOwnedPluginContext(plugin, options = {}) {
     const disposables = options.disposables ?? [];
     const context = {
         plugin,
+        ...(options.host !== undefined ? { host: options.host } : {}),
         signal: abortController.signal,
         container: options.container,
         config: options.config,
@@ -43,4 +44,3 @@ export function createOwnedPluginContext(plugin, options = {}) {
 export function createPluginContext(plugin, options = {}) {
     return createOwnedPluginContext(plugin, options).context;
 }
-//# sourceMappingURL=pluginContext.core.js.map

package/dist/pluginLifecycle/pluginLifecycle.abandoned.d.ts

@@ -27,4 +27,3 @@ export declare class AbandonedHooks {
         hook: Promise<void>;
     } | undefined>;
 }
-//# sourceMappingURL=pluginLifecycle.abandoned.d.ts.map

package/dist/pluginLifecycle/pluginLifecycle.abandoned.js

@@ -43,4 +43,3 @@ export class AbandonedHooks {
         }
     }
 }
-//# sourceMappingURL=pluginLifecycle.abandoned.js.map

package/dist/pluginLifecycle/pluginLifecycle.core.d.ts

@@ -25,6 +25,11 @@ export declare class LifecycleController {
     /**
      * Runs a hook under the configured timeout, clearing the timer either
      * way so a completed hook never leaves one armed.
+     *
+     * The timer is deliberately ref'd: it guards pending work, and an
+     * unref'd one let Node exit (code 13, "unsettled top-level await")
+     * when a `start()` hook hung before anything else held the event
+     * loop, so no `PluginTimeoutError` was raised and nothing rolled back.
      */
     private runHook;
     install<TPlugin extends Plugin>(registered: RegisteredPlugin<TPlugin>, context: PluginContext): Promise<void>;
@@ -63,4 +68,3 @@ export declare class LifecycleController {
     private canTransition;
     private ensureTransition;
 }
-//# sourceMappingURL=pluginLifecycle.core.d.ts.map

package/dist/pluginLifecycle/pluginLifecycle.core.js

@@ -2,6 +2,7 @@ import { isValidTransition } from "../pluginTypes/pluginState.type.js";
 import { PluginDisposeError, PluginStateError, PluginTimeoutError, } from "@zudojs/errors";
 import { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "../pluginEvents/pluginEvent.core.js";
 import { AbandonedHooks } from "./pluginLifecycle.abandoned.js";
+import { toPhaseError } from "./pluginLifecycle.phaseError.js";
 import { reportPluginFailure } from "./pluginLifecycle.report.js";
 import { deliverPluginEvent } from "../pluginEvents/pluginEvent.deliver.js";
 /**
@@ -36,6 +37,11 @@ export class LifecycleController {
     /**
      * Runs a hook under the configured timeout, clearing the timer either
      * way so a completed hook never leaves one armed.
+     *
+     * The timer is deliberately ref'd: it guards pending work, and an
+     * unref'd one let Node exit (code 13, "unsettled top-level await")
+     * when a `start()` hook hung before anything else held the event
+     * loop, so no `PluginTimeoutError` was raised and nothing rolled back.
      */
     async runHook(pluginName, phase, run, onAbandoned) {
         const timeout = this.options.hookTimeout ?? 0;
@@ -58,7 +64,6 @@ export class LifecycleController {
                             metadata: { phase },
                         }));
                     }, Math.min(timeout, MAX_TIMER_DELAY));
-                    timer.unref?.();
                 }),
             ]);
         }
@@ -100,10 +105,12 @@ export class LifecycleController {
             emitLifecycleEvent(context, endEvent, metadata, settled, transient);
         }
         catch (error) {
+            // Diagnostics and the `failed` event keep what the hook threw; the
+            // caller gets it wrapped in the phase's error, naming the plugin.
             registered.setError(error);
             this.transitionToFailed(registered);
             emitLifecycleEvent(context, PLUGIN_EVENTS.FAILED, metadata, "failed", transient, error);
-            throw error;
+            throw toPhaseError(transient, metadata.name, error);
         }
     }
     /**
@@ -218,4 +225,3 @@ export class LifecycleController {
         }
     }
 }
-//# sourceMappingURL=pluginLifecycle.core.js.map

package/dist/pluginLifecycle/pluginLifecycle.phaseError.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Wraps a lifecycle hook's failure in the typed error for its phase.
+ *
+ * `PluginInitializationError`, `PluginStartError` and `PluginStopError`
+ * were exported but never thrown: a hook's raw error was rethrown as-is,
+ * so nothing but `diagnostics()` said which plugin had failed. The wrap
+ * names the plugin and the phase and keeps the original as `cause`.
+ *
+ * @module pluginLifecycle/pluginLifecycle.phaseError
+ */
+import type { PluginState } from "../pluginTypes/pluginState.type.js";
+/**
+ * Returns the error to throw for a hook that failed in `phase`.
+ *
+ * A `PluginError` — a `PluginTimeoutError`, `PluginStateError`, or a
+ * typed error a plugin threw on purpose — already names the plugin and
+ * lets callers branch on it, so it propagates unchanged. Anything else is
+ * wrapped in the phase's error class with the original as `cause`; the
+ * message quotes the original's so existing substring matches still hold.
+ */
+export declare function toPhaseError(phase: PluginState, pluginName: string, error: unknown): unknown;

package/dist/pluginLifecycle/pluginLifecycle.phaseError.js

@@ -0,0 +1,43 @@
+/**
+ * Wraps a lifecycle hook's failure in the typed error for its phase.
+ *
+ * `PluginInitializationError`, `PluginStartError` and `PluginStopError`
+ * were exported but never thrown: a hook's raw error was rethrown as-is,
+ * so nothing but `diagnostics()` said which plugin had failed. The wrap
+ * names the plugin and the phase and keeps the original as `cause`.
+ *
+ * @module pluginLifecycle/pluginLifecycle.phaseError
+ */
+import { PluginError, PluginInitializationError, PluginStartError, PluginStopError, } from "@zudojs/errors";
+/** The lifecycle-hook error class for each transient phase. */
+const PHASE_ERRORS = {
+    installing: PluginInitializationError,
+    initializing: PluginInitializationError,
+    starting: PluginStartError,
+    stopping: PluginStopError,
+};
+/** The verb a phase's failure message uses. */
+const PHASE_VERBS = {
+    installing: "install",
+    initializing: "initialize",
+    starting: "start",
+    stopping: "stop",
+};
+/**
+ * Returns the error to throw for a hook that failed in `phase`.
+ *
+ * A `PluginError` — a `PluginTimeoutError`, `PluginStateError`, or a
+ * typed error a plugin threw on purpose — already names the plugin and
+ * lets callers branch on it, so it propagates unchanged. Anything else is
+ * wrapped in the phase's error class with the original as `cause`; the
+ * message quotes the original's so existing substring matches still hold.
+ */
+export function toPhaseError(phase, pluginName, error) {
+    if (error instanceof PluginError)
+        return error;
+    const PhaseError = PHASE_ERRORS[phase];
+    if (PhaseError === undefined)
+        return error;
+    const detail = error instanceof Error ? error.message : String(error);
+    return new PhaseError(`Plugin "${pluginName}" failed to ${PHASE_VERBS[phase]}: ${detail}`, pluginName, { cause: error });
+}

package/dist/pluginLifecycle/pluginLifecycle.report.d.ts

@@ -13,4 +13,3 @@ import type { PluginLogger } from "../pluginTypes/pluginContext.type.js";
  * @param fields - Extra structured context.
  */
 export declare function reportPluginFailure(logger: PluginLogger | undefined, message: string, error: unknown, fields?: Record<string, unknown>): void;
-//# sourceMappingURL=pluginLifecycle.report.d.ts.map

package/dist/pluginLifecycle/pluginLifecycle.report.js

@@ -28,4 +28,3 @@ export function reportPluginFailure(logger, message, error, fields = {}) {
         detail,
     });
 }
-//# sourceMappingURL=pluginLifecycle.report.js.map

package/dist/pluginManager/pluginManager.core.d.ts

@@ -85,10 +85,15 @@ export declare class PluginManager {
     /**
      * Registers a plugin.
      *
+     * `options` is typed from the plugin: for a `Plugin<TOptions>` (a
+     * plugin whose `install(context, options)` declares its options type)
+     * it must be a `TOptions`, so a mistyped options object is a compile
+     * error rather than a runtime surprise in `install`.
+     *
      * @throws {PluginAlreadyRegisteredError} when the name is taken, so
      * callers can implement idempotent registration.
      */
-    register<TPlugin extends Plugin>(plugin: TPlugin, options?: unknown): void;
+    register<TOptions = unknown>(plugin: Plugin<TOptions>, options?: TOptions): void;
     /**
      * Removes a plugin that has not been started.
      *
@@ -151,4 +156,3 @@ export declare class PluginManager {
     private report;
     private toDependencyMap;
 }
-//# sourceMappingURL=pluginManager.core.d.ts.map

package/dist/pluginManager/pluginManager.core.js

@@ -61,6 +61,11 @@ export class PluginManager {
     /**
      * Registers a plugin.
      *
+     * `options` is typed from the plugin: for a `Plugin<TOptions>` (a
+     * plugin whose `install(context, options)` declares its options type)
+     * it must be a `TOptions`, so a mistyped options object is a compile
+     * error rather than a runtime surprise in `install`.
+     *
      * @throws {PluginAlreadyRegisteredError} when the name is taken, so
      * callers can implement idempotent registration.
      */
@@ -302,6 +307,10 @@ export class PluginManager {
             logger: base.logger,
             events: base.events,
             disposables: registered.disposables,
+            // The host's own metadata used to be dropped here: every plugin saw
+            // only itself under `context.plugin` and had no way to learn which
+            // application was hosting it.
+            host: base.host ?? base.plugin,
         });
         this.contexts.set(name, { context: owned.context, abort: owned.abort });
         return owned.context;
@@ -347,4 +356,3 @@ export class PluginManager {
         return map;
     }
 }
-//# sourceMappingURL=pluginManager.core.js.map

package/dist/pluginRegistry/index.d.ts

@@ -5,4 +5,3 @@
  */
 export type { PluginRegistry, RegisteredPlugin, } from "./pluginRegistry.core.js";
 export { PluginRegistryImpl } from "./pluginRegistry.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/pluginRegistry/index.js

@@ -4,4 +4,3 @@
  * Plugin registry for storing and retrieving registered plugins.
  */
 export { PluginRegistryImpl } from "./pluginRegistry.core.js";
-//# sourceMappingURL=index.js.map

package/dist/pluginRegistry/pluginRegistry.core.d.ts

@@ -47,4 +47,3 @@ export declare class PluginRegistryImpl implements PluginRegistry {
     remove(name: string): boolean;
     clear(): void;
 }
-//# sourceMappingURL=pluginRegistry.core.d.ts.map

package/dist/pluginRegistry/pluginRegistry.core.js

@@ -53,4 +53,3 @@ export class PluginRegistryImpl {
         this.plugins.clear();
     }
 }
-//# sourceMappingURL=pluginRegistry.core.js.map

package/dist/pluginTypes/index.d.ts

@@ -8,5 +8,5 @@ export type { PluginMetadata } from "./pluginMetadata.type.js";
 export type { PluginDependency } from "./pluginDependency.type.js";
 export type { PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginEventBus, PluginEventSource, PluginDisposable, } from "./pluginContext.type.js";
 export type { Plugin } from "./plugin.type.js";
+export type { PluginHealth, PluginHealthStatus } from "./plugin.type.js";
 export type { PluginErrorOptions } from "@zudojs/errors";
-//# sourceMappingURL=index.d.ts.map

package/dist/pluginTypes/index.js

@@ -4,4 +4,3 @@
  * Core types for the Zudojs plugin system.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/pluginTypes/plugin.type.d.ts

@@ -1,6 +1,18 @@
 import type { PluginMetadata } from "./pluginMetadata.type.js";
 import type { PluginDependency } from "./pluginDependency.type.js";
 import type { PluginContext } from "./pluginContext.type.js";
+/**
+ * Plugin health status.
+ */
+export type PluginHealthStatus = "healthy" | "degraded" | "unhealthy";
+/**
+ * Plugin health information: what a plugin's own `health()` returns and
+ * what `PluginManager.diagnostics()` reports for it.
+ */
+export interface PluginHealth {
+    readonly status: PluginHealthStatus;
+    readonly details?: unknown;
+}
 /**
  * Plugin interface definition.
  */
@@ -13,5 +25,11 @@ export interface Plugin<TOptions = unknown> {
     start?(context: PluginContext): void | Promise<void>;
     stop?(context: PluginContext): void | Promise<void>;
     dispose?(context: PluginContext): void | Promise<void>;
+    /**
+     * Reports the plugin's own health while it is `started`. Consulted by
+     * `PluginManager.diagnostics()`, which otherwise derives health from
+     * lifecycle state alone; a throwing `health()` is reported as
+     * `unhealthy` with the error message as `details`.
+     */
+    health?(): PluginHealth;
 }
-//# sourceMappingURL=plugin.type.d.ts.map

package/dist/pluginTypes/plugin.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=plugin.type.js.map

package/dist/pluginTypes/pluginContext.type.d.ts

@@ -1,9 +1,16 @@
 import type { PluginMetadata } from "./pluginMetadata.type.js";
 /**
  * Minimal container interface for plugin context.
+ *
+ * `register` is all the plugin system itself needs. `resolve` and `has`
+ * are declared optional so a plugin can read from a real container
+ * (`@zudojs/container`'s satisfies this shape) without casting; a host
+ * that passes a register-only object leaves them `undefined`.
  */
 export interface PluginContainer {
     register(token: unknown, provider: unknown): void;
+    resolve?<T = unknown>(token: unknown): T;
+    has?(token: unknown): boolean;
 }
 /**
  * Minimal config interface for plugin context.
@@ -63,6 +70,12 @@ export interface PluginDisposable {
  */
 export interface PluginContext {
     readonly plugin: PluginMetadata;
+    /**
+     * Metadata of the host application — the `plugin` metadata of the
+     * context handed to `PluginManager.start()`. Absent on a context built
+     * directly with `createPluginContext` and no `host` option.
+     */
+    readonly host?: PluginMetadata;
     readonly container?: PluginContainer;
     readonly config?: PluginConfig;
     readonly logger?: PluginLogger;
@@ -75,4 +88,3 @@ export interface PluginContext {
     onDispose(handler: () => void | Promise<void>): void;
     registerDisposable(disposable: PluginDisposable): void;
 }
-//# sourceMappingURL=pluginContext.type.d.ts.map

package/dist/pluginTypes/pluginContext.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=pluginContext.type.js.map

package/dist/pluginTypes/pluginDependency.type.d.ts

@@ -11,4 +11,3 @@ export interface PluginDependency {
      */
     readonly optional?: boolean;
 }
-//# sourceMappingURL=pluginDependency.type.d.ts.map

package/dist/pluginTypes/pluginDependency.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=pluginDependency.type.js.map

package/dist/pluginTypes/pluginMetadata.type.d.ts

@@ -10,4 +10,3 @@ export interface PluginMetadata {
     readonly keywords?: readonly string[];
     readonly capabilities?: readonly string[];
 }
-//# sourceMappingURL=pluginMetadata.type.d.ts.map

package/dist/pluginTypes/pluginMetadata.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=pluginMetadata.type.js.map

package/dist/pluginTypes/pluginState.type.d.ts

@@ -10,4 +10,3 @@ export declare const VALID_STATE_TRANSITIONS: Readonly<Record<PluginState, reado
  * Determines whether a state transition is valid.
  */
 export declare function isValidTransition(from: PluginState, to: PluginState): boolean;
-//# sourceMappingURL=pluginState.type.d.ts.map

package/dist/pluginTypes/pluginState.type.js

@@ -24,4 +24,3 @@ export const VALID_STATE_TRANSITIONS = {
 export function isValidTransition(from, to) {
     return VALID_STATE_TRANSITIONS[from]?.includes(to) ?? false;
 }
-//# sourceMappingURL=pluginState.type.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/plugins",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Plugin system for extending Zudojs applications with modular capabilities.",
   "license": "MIT",
   "author": {
@@ -24,11 +24,11 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.3.1"
+    "@zudojs/errors": "1.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.2",
-    "@zudojs/events": "1.3.2",
+    "@zudojs/events": "1.4.0",
     "typescript": "7.0.2",
     "vitest": "^5.0.1"
   },