@zudojs/plugins 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,16 @@
 # @zudojs/plugins
 
-Plugin manager, registry, dependency resolver, lifecycle controller, events, and integration context. The basis for extending a Zudojs app with third-party functionality.
+Plugin manager, registry, dependency resolver, lifecycle controller, events, and diagnostics. The basis for extending a Zudojs app with third-party functionality.
 
 ## When to use
 
 Import this when you need:
 
-- load a plugin from a manifest or package
-- resolve plugin dependencies before activation
-- run plugin lifecycle hooks (install → enable → disable → uninstall)
-- isolate plugin state via a `PluginContext`
+- register extensions and bring them up in dependency order
+- enforce declared dependency versions before anything starts
+- run plugin lifecycle hooks (`install` → `initialize` → `start` → `stop` → `dispose`)
+- give each plugin a scoped `PluginContext` with its own disposables and abort signal
+- roll back cleanly when one plugin fails to start
 
 ## Installation
 
@@ -17,41 +18,141 @@ Import this when you need:
 npm install @zudojs/plugins
 ```
 
-## Public API
+## Quick start
 
 ```typescript
-import {
-  PluginManager,
-  PluginRegistryImpl,
-  PluginLifecycleController,
-  createPluginContext,
-  createEventEmitter,
-  type PluginDefinition,
-  type PluginMetadata,
-  type PluginContext,
-  type PluginLifecycleEvent,
-  type PluginHook,
-  type DependencyResolution,
-  type CreatePluginContextOptions,
-  type PluginHooks,
-} from "@zudojs/plugins";
+import { PluginManager, createPluginContext } from "@zudojs/plugins";
+
+const manager = new PluginManager({ hookTimeout: 5_000 });
+
+manager.register({
+  metadata: { name: "@acme/db", version: "1.0.0" },
+  async start(context) {
+    const pool = openPool();
+    // Released automatically, in reverse registration order, on dispose.
+    context.registerDisposable({ dispose: () => pool.end() });
+  },
+});
+
+manager.register({
+  metadata: { name: "@acme/api" },
+  dependencies: [{ name: "@acme/db", version: "^1.0.0" }],
+  async start(context) {
+    context.logger?.info("api started");
+  },
+});
+
+const context = createPluginContext({ name: "@acme/host" });
+
+await manager.start(context); // @acme/db first, then @acme/api
+await manager.stop(context); // reverse order; disposables released
 ```
 
-## Usage
+`createPluginContext` takes the host's own `PluginMetadata` and, optionally,
+the services plugins may reach (`container`, `config`, `logger`, `events`).
+The manager derives a per-plugin view of it: `context.plugin` names the
+plugin currently running, `context.registerDisposable` and
+`context.onDispose` write to that plugin's own cleanup list, and
+`context.signal` is aborted when the plugin system shuts down.
+
+## Lifecycle
+
+| Phase | Called by | Runs |
+| --- | --- | --- |
+| `install(context, options)` | `manager.start` | once, in dependency order |
+| `initialize(context)` | `manager.start` | after every plugin is installed |
+| `start(context)` | `manager.start` | after every plugin is initialized |
+| `stop(context)` | `manager.stop` | reverse dependency order |
+| `dispose(context)` | `manager.stop` | after `stop`, releasing disposables |
+
+Every hook is optional. Each phase completes across all plugins before the
+next begins, so a plugin may rely on its dependencies being installed by
+the time its own `initialize` runs.
+
+If any phase throws, `manager.start` stops and disposes everything it had
+already brought up, then rethrows. `manager.stop` continues past a failing
+plugin so one bad `stop` cannot strand the rest; those failures are
+reported through the `onError` option (and logged to `console.error` if you
+do not supply one) rather than swallowed.
+
+## Dependency order and versions
+
+Required dependencies must be registered, or `start` throws
+`PluginDependencyError` naming both the plugin that declared the dependency
+and the dependency itself. Cycles throw `PluginDependencyCycleError` with
+the cycle path. Optional dependencies that are present still participate in
+ordering; optional dependencies that are absent are ignored.
+
+Declared versions are enforced before any hook runs:
 
 ```typescript
-import { PluginManager, createPluginContext } from "@zudojs/plugins";
+manager.register({ metadata: { name: "@acme/db", version: "1.4.0" } });
+manager.register({
+  metadata: { name: "@acme/api" },
+  dependencies: [{ name: "@acme/db", version: "^2.0.0" }],
+});
 
-const ctx = createPluginContext({ logger, config });
-const manager = new PluginManager(ctx);
+await manager.start(context);
+// PluginDependencyVersionError: Plugin "@acme/api" requires "@acme/db@^2.0.0",
+// but version 1.4.0 is registered. Register a "@acme/db" that satisfies
+// ^2.0.0, relax the constraint on "@acme/api", or construct the manager
+// with { checkVersions: false }.
+```
 
-await manager.load({
-  name: "audit-log",
-  version: "1.0.0",
-  activate: async (ctx) => ctx.logger.info("audit-log activated"),
+Supported range forms are an exact version (`1.2.3`), caret and tilde
+(`^1.2.3`, `~1.2.3`), comparators (`>=1.2.3`, `>`, `<=`, `<`) and `*`.
+Pass `{ checkVersions: false }` to skip the check.
+
+## Manager options
+
+```typescript
+new PluginManager({
+  checkVersions: true, // enforce declared dependency versions (default)
+  hookTimeout: 5_000, // bound each lifecycle hook; 0 = unbounded (default)
+  onError: (error, pluginName) => report(error, pluginName), // teardown failures
+  allowedCapabilities: ["http", "db"], // reject plugins requesting anything else
+  events: eventSink, // receives `plugin:registered`
 });
 ```
 
+## Events
+
+Lifecycle events are emitted on `context.events` if you supply one, and
+`plugin:registered` on the manager's own `events` option. Names are in
+`PLUGIN_EVENTS`; payloads are `PluginLifecycleEvent`.
+
+```typescript
+import { PLUGIN_EVENTS } from "@zudojs/plugins";
+
+const manager = new PluginManager({
+  events: {
+    on() {},
+    off() {},
+    emit(name, payload) {
+      if (name === PLUGIN_EVENTS.REGISTERED) console.log(payload);
+    },
+  },
+});
+```
+
+A throwing subscriber never fails the phase that emitted the event.
+
+## Diagnostics
+
+```typescript
+const report = manager.diagnostics();
+
+report.total; // plugins registered
+report.healthy; // started and not failed
+report.degraded; // registered but not started
+report.unhealthy; // failed at some point
+report.plugins[0].state; // "started" | "failed" | ...
+report.plugins[0].health.details; // failure message, when unhealthy
+```
+
+A plugin that failed and was then disposed during rollback is still
+reported as failed: the current state alone would not show it.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -3,42 +3,63 @@
  *
  * Controlled extension system for the Zudojs framework.
  *
- * Provides plugin registration, dependency resolution, lifecycle management,
- * and orchestration for Zudojs applications.
+ * Provides plugin registration, dependency resolution, lifecycle
+ * management, and orchestration for Zudojs applications.
+ *
+ * Plugins move through `install` -> `initialize` -> `start` on the way up
+ * and `stop` -> `dispose` on the way down. The manager runs each phase
+ * across every plugin in dependency order, and rolls back everything it
+ * brought up if any phase fails.
  *
  * @example
  * ```ts
  * import { PluginManager, createPluginContext } from "@zudojs/plugins";
  *
- * const manager = new PluginManager();
+ * const manager = new PluginManager({ hookTimeout: 5_000 });
  *
  * manager.register({
- *   metadata: { name: "@zudojs/http" },
- *   dependencies: [{ name: "@zudojs/events" }],
- *   async install(context) {
- *     // register services
+ *   metadata: { name: "@acme/db", version: "1.0.0" },
+ *   async start(context) {
+ *     const pool = openPool();
+ *     context.registerDisposable({ dispose: () => pool.end() });
  *   },
+ * });
+ *
+ * manager.register({
+ *   metadata: { name: "@acme/api" },
+ *   dependencies: [{ name: "@acme/db", version: "^1.0.0" }],
  *   async start(context) {
- *     // begin active work
+ *     context.logger?.info("api started");
  *   },
  * });
  *
- * await manager.start(createPluginContext({ metadata: { name: "@zudojs/http" } }));
+ * // `createPluginContext` takes the host's own metadata plus the
+ * // services plugins are allowed to reach. Each plugin is handed its
+ * // own view of it, naming that plugin.
+ * const context = createPluginContext({ name: "@acme/host" });
+ *
+ * await manager.start(context); // @acme/db, then @acme/api
+ * await manager.stop(context);  // reverse order; disposables released
  * ```
  */
 export { PluginManager } from "./pluginManager/pluginManager.core.js";
+export type { PluginManagerOptions } from "./pluginManager/pluginManager.core.js";
 export { PluginRegistryImpl } from "./pluginRegistry/pluginRegistry.core.js";
 export type { PluginRegistry, RegisteredPlugin, } from "./pluginRegistry/pluginRegistry.core.js";
 export { DependencyResolver, assertResolutionValid, } from "./pluginDependencies/dependencyResolver.core.js";
-export type { DependencyResolution } from "./pluginDependencies/dependencyResolver.core.js";
+export type { DependencyResolution, MissingDependency, ResolvablePlugin, } from "./pluginDependencies/dependencyResolver.core.js";
+export { parseVersion, compareVersions, satisfiesVersion, assertDependencyVersions, } from "./pluginDependencies/versionCheck.core.js";
+export type { SemVer } from "./pluginDependencies/versionCheck.core.js";
+export { PluginDependencyVersionError } from "./pluginDependencies/versionCheck.core.js";
 export { LifecycleController } from "./pluginLifecycle/pluginLifecycle.core.js";
+export type { LifecycleControllerOptions } from "./pluginLifecycle/pluginLifecycle.core.js";
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvents/pluginEvent.core.js";
 export type { PluginLifecycleEvent } from "./pluginEvents/pluginEvent.core.js";
 export { buildDiagnosticReport, 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 } from "./pluginIntegration/pluginContext.core.js";
-export type { CreatePluginContextOptions } from "./pluginIntegration/pluginContext.core.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, Plugin, PluginErrorOptions, } from "./pluginTypes/index.js";
+export type { PluginState, PluginMetadata, PluginDependency, PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginDisposable, Plugin, PluginErrorOptions, } from "./pluginTypes/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,36 +3,54 @@
  *
  * Controlled extension system for the Zudojs framework.
  *
- * Provides plugin registration, dependency resolution, lifecycle management,
- * and orchestration for Zudojs applications.
+ * Provides plugin registration, dependency resolution, lifecycle
+ * management, and orchestration for Zudojs applications.
+ *
+ * Plugins move through `install` -> `initialize` -> `start` on the way up
+ * and `stop` -> `dispose` on the way down. The manager runs each phase
+ * across every plugin in dependency order, and rolls back everything it
+ * brought up if any phase fails.
  *
  * @example
  * ```ts
  * import { PluginManager, createPluginContext } from "@zudojs/plugins";
  *
- * const manager = new PluginManager();
+ * const manager = new PluginManager({ hookTimeout: 5_000 });
  *
  * manager.register({
- *   metadata: { name: "@zudojs/http" },
- *   dependencies: [{ name: "@zudojs/events" }],
- *   async install(context) {
- *     // register services
+ *   metadata: { name: "@acme/db", version: "1.0.0" },
+ *   async start(context) {
+ *     const pool = openPool();
+ *     context.registerDisposable({ dispose: () => pool.end() });
  *   },
+ * });
+ *
+ * manager.register({
+ *   metadata: { name: "@acme/api" },
+ *   dependencies: [{ name: "@acme/db", version: "^1.0.0" }],
  *   async start(context) {
- *     // begin active work
+ *     context.logger?.info("api started");
  *   },
  * });
  *
- * await manager.start(createPluginContext({ metadata: { name: "@zudojs/http" } }));
+ * // `createPluginContext` takes the host's own metadata plus the
+ * // services plugins are allowed to reach. Each plugin is handed its
+ * // own view of it, naming that plugin.
+ * const context = createPluginContext({ name: "@acme/host" });
+ *
+ * await manager.start(context); // @acme/db, then @acme/api
+ * await manager.stop(context);  // reverse order; disposables released
  * ```
  */
 export { PluginManager } from "./pluginManager/pluginManager.core.js";
 export { PluginRegistryImpl } from "./pluginRegistry/pluginRegistry.core.js";
 export { DependencyResolver, assertResolutionValid, } from "./pluginDependencies/dependencyResolver.core.js";
+export { parseVersion, compareVersions, satisfiesVersion, assertDependencyVersions, } from "./pluginDependencies/versionCheck.core.js";
+export { PluginDependencyVersionError } from "./pluginDependencies/versionCheck.core.js";
 export { LifecycleController } from "./pluginLifecycle/pluginLifecycle.core.js";
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvents/pluginEvent.core.js";
 export { buildDiagnosticReport, createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
 export { isValidTransition, VALID_STATE_TRANSITIONS, } from "./pluginTypes/pluginState.type.js";
-export { createPluginContext } from "./pluginIntegration/pluginContext.core.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

@@ -1,10 +1,34 @@
 import type { PluginDependency } from "../pluginTypes/pluginDependency.type.js";
+/**
+ * The dependency shape the resolver needs from a plugin.
+ */
+export interface ResolvablePlugin {
+    readonly dependencies?: readonly PluginDependency[];
+    readonly optionalDependencies?: readonly PluginDependency[];
+}
+/**
+ * A dependency that could not be satisfied.
+ */
+export interface MissingDependency {
+    /** The plugin that declared the dependency. */
+    readonly plugin: string;
+    /** The dependency it needs. */
+    readonly dependency: string;
+}
 /**
  * Result of dependency resolution.
  */
 export interface DependencyResolution {
     readonly ordered: readonly string[];
+    /**
+     * Names of required dependencies that are not registered.
+     *
+     * Retained as plain names for compatibility; {@link missingDetails}
+     * also records which plugin declared each one.
+     */
     readonly missing: readonly string[];
+    /** Missing dependencies, with the plugin that declared each. */
+    readonly missingDetails: readonly MissingDependency[];
     readonly cycles: readonly string[];
 }
 /**
@@ -13,16 +37,33 @@ export interface DependencyResolution {
 export declare class DependencyResolver {
     /**
      * Resolves dependencies for the given plugins.
+     *
+     * Optional dependencies that are present participate in ordering — a
+     * plugin that optionally integrates with a peer must still start after
+     * it — while optional dependencies that are absent are ignored rather
+     * than reported missing.
+     */
+    resolve(plugins: Map<string, ResolvablePlugin>): DependencyResolution;
+    /**
+     * Returns the edges a plugin depends on, in declaration order.
+     *
+     * Only dependencies that are actually registered become edges, so an
+     * absent optional dependency does not create a dangling node.
+     */
+    private edgesFor;
+    /**
+     * Produces a dependency-first ordering, recording any cycles found.
+     *
+     * The traversal keeps its own stack rather than recursing, so a deep
+     * dependency chain reports a graph result instead of overflowing.
      */
-    resolve(plugins: Map<string, {
-        readonly dependencies?: readonly PluginDependency[];
-        readonly optionalDependencies?: readonly PluginDependency[];
-    }>): DependencyResolution;
-    private dfs;
-    private extractCycle;
+    private topologicalOrder;
 }
 /**
  * Throws if the dependency resolution has errors.
+ *
+ * The thrown error names both the plugin that declared the dependency
+ * 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

@@ -5,79 +5,141 @@ import { PluginDependencyCycleError, PluginDependencyError, } from "@zudojs/erro
 export class DependencyResolver {
     /**
      * Resolves dependencies for the given plugins.
+     *
+     * Optional dependencies that are present participate in ordering — a
+     * plugin that optionally integrates with a peer must still start after
+     * it — while optional dependencies that are absent are ignored rather
+     * than reported missing.
      */
     resolve(plugins) {
-        const missing = [];
+        const missingDetails = [];
         const cycles = [];
         for (const [name, plugin] of plugins) {
             for (const dep of plugin.dependencies ?? []) {
                 if (!plugins.has(dep.name)) {
-                    missing.push(dep.name);
+                    missingDetails.push({ plugin: name, dependency: dep.name });
                 }
             }
         }
-        if (missing.length > 0) {
-            return { ordered: [], missing, cycles };
-        }
-        const visited = new Set();
-        const visiting = new Set();
-        const order = [];
-        for (const name of plugins.keys()) {
-            if (!visited.has(name)) {
-                const cycle = this.dfs(name, plugins, visited, visiting, order);
-                if (cycle) {
-                    cycles.push(cycle);
-                }
-            }
+        const missing = missingDetails.map((entry) => entry.dependency);
+        if (missingDetails.length > 0) {
+            return Object.freeze({
+                ordered: Object.freeze([]),
+                missing: Object.freeze(missing),
+                missingDetails: Object.freeze(missingDetails),
+                cycles: Object.freeze(cycles),
+            });
         }
+        const order = this.topologicalOrder(plugins, cycles);
         if (cycles.length > 0) {
-            return { ordered: [], missing, cycles };
+            return Object.freeze({
+                ordered: Object.freeze([]),
+                missing: Object.freeze(missing),
+                missingDetails: Object.freeze(missingDetails),
+                cycles: Object.freeze(cycles),
+            });
         }
-        return {
+        return Object.freeze({
             ordered: Object.freeze(order),
-            missing,
+            missing: Object.freeze(missing),
+            missingDetails: Object.freeze(missingDetails),
             cycles: Object.freeze(cycles),
-        };
+        });
     }
-    dfs(name, plugins, visited, visiting, order) {
-        if (visiting.has(name)) {
-            const cycle = this.extractCycle(name, visiting);
-            return cycle;
+    /**
+     * Returns the edges a plugin depends on, in declaration order.
+     *
+     * Only dependencies that are actually registered become edges, so an
+     * absent optional dependency does not create a dangling node.
+     */
+    edgesFor(name, plugins) {
+        const plugin = plugins.get(name);
+        if (!plugin) {
+            return [];
         }
-        if (visited.has(name)) {
-            return undefined;
+        const edges = [];
+        for (const dep of plugin.dependencies ?? []) {
+            if (plugins.has(dep.name)) {
+                edges.push(dep.name);
+            }
         }
-        visiting.add(name);
-        const plugin = plugins.get(name);
-        const deps = plugin?.dependencies ?? [];
-        for (const dep of deps) {
-            const cycle = this.dfs(dep.name, plugins, visited, visiting, order);
-            if (cycle) {
-                return cycle;
+        for (const dep of plugin.optionalDependencies ?? []) {
+            if (plugins.has(dep.name) && !edges.includes(dep.name)) {
+                edges.push(dep.name);
             }
         }
-        visiting.delete(name);
-        visited.add(name);
-        order.push(name);
-        return undefined;
+        return edges;
     }
-    extractCycle(entryPoint, visiting) {
-        const cycle = [entryPoint];
-        let current = entryPoint;
-        const entries = Array.from(visiting);
-        const startIndex = entries.indexOf(current);
-        for (let i = startIndex + 1; i < entries.length; i++) {
-            cycle.push(entries[i]);
-            current = entries[i];
+    /**
+     * Produces a dependency-first ordering, recording any cycles found.
+     *
+     * The traversal keeps its own stack rather than recursing, so a deep
+     * dependency chain reports a graph result instead of overflowing.
+     */
+    topologicalOrder(plugins, cycles) {
+        const visited = new Set();
+        const onStack = new Set();
+        const order = [];
+        for (const root of plugins.keys()) {
+            if (visited.has(root)) {
+                continue;
+            }
+            // Each frame tracks how many of the node's edges have been walked.
+            const stack = [
+                { name: root, edgeIndex: 0, path: [root] },
+            ];
+            onStack.add(root);
+            while (stack.length > 0) {
+                const frame = stack[stack.length - 1];
+                const edges = this.edgesFor(frame.name, plugins);
+                if (frame.edgeIndex >= edges.length) {
+                    onStack.delete(frame.name);
+                    visited.add(frame.name);
+                    order.push(frame.name);
+                    stack.pop();
+                    continue;
+                }
+                const next = edges[frame.edgeIndex];
+                frame.edgeIndex += 1;
+                if (onStack.has(next)) {
+                    const start = frame.path.indexOf(next);
+                    const cycle = start >= 0 ? frame.path.slice(start) : [next, frame.name];
+                    cycles.push([...cycle, next].join(" -> "));
+                    // Unwind: an ordering cannot be produced for a cyclic graph.
+                    for (const remaining of stack) {
+                        onStack.delete(remaining.name);
+                    }
+                    stack.length = 0;
+                    break;
+                }
+                if (visited.has(next)) {
+                    continue;
+                }
+                onStack.add(next);
+                stack.push({
+                    name: next,
+                    edgeIndex: 0,
+                    path: [...frame.path, next],
+                });
+            }
+            if (cycles.length > 0) {
+                break;
+            }
         }
-        cycle.push(entryPoint);
-        return cycle.join(" -> ");
+        return order;
     }
 }
 /**
  * Throws if the dependency resolution has errors.
+ *
+ * The thrown error names both the plugin that declared the dependency
+ * and the dependency itself, so a startup failure says who needed what.
  */
 export function assertResolutionValid(resolution) {
+    const missing = resolution.missingDetails[0];
+    if (missing) {
+        throw new PluginDependencyError(missing.plugin, missing.dependency);
+    }
     if (resolution.missing.length > 0) {
         throw new PluginDependencyError(resolution.missing[0], resolution.missing[0]);
     }

package/dist/pluginDependencies/index.d.ts

@@ -1,8 +1,12 @@
 /**
  * @zudojs/plugins/pluginDependencies
  *
- * Plugin dependency resolution, topological sorting, and cycle detection.
+ * Plugin dependency resolution, topological sorting, cycle detection,
+ * and version constraint checking.
  */
-export type { DependencyResolution } from "./dependencyResolver.core.js";
+export type { DependencyResolution, MissingDependency, ResolvablePlugin, } from "./dependencyResolver.core.js";
 export { DependencyResolver, assertResolutionValid, } from "./dependencyResolver.core.js";
+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

@@ -1,7 +1,10 @@
 /**
  * @zudojs/plugins/pluginDependencies
  *
- * Plugin dependency resolution, topological sorting, and cycle detection.
+ * Plugin dependency resolution, topological sorting, cycle detection,
+ * and version constraint checking.
  */
 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