@zudojs/plugins 1.0.0 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Plugin manager, registry, dependency resolver, lifecycle controller, events, and diagnostics. The basis for extending a Zudojs app with third-party functionality.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-plugins](https://zudojs.oyinlola.site/docs/packages-plugins) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-plugins.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## When to use
 
 Import this when you need:
@@ -70,10 +76,23 @@ 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
+already brought up, then rethrows. A disposed plugin cannot be brought back:
+calling `manager.start` again after `manager.stop`, or after a rolled-back
+startup, throws `PluginStateError` rather than silently starting nothing (or
+starting still-registered dependents on top of disposed dependencies).
+Unregister the disposed plugins and register fresh instances, or create a
+new manager. `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.
+reported through the `onError` option rather than swallowed. Without
+`onError` they go to the `logger` option, or else the logger on the
+context passed to `start()`/`stop()`; with no logger at all they are
+raised as a `ZudoPluginWarning` process warning.
+
+A hook that exceeds `hookTimeout` keeps running (it cannot be cancelled).
+Before a plugin whose hook timed out is disposed, the manager waits up to
+another `hookTimeout` for that hook to settle, and calls `stop()` if a
+timed-out `start()` went on to succeed. If `start()` finishes even later,
+`stop()` runs as soon as it does.
 
 ## Dependency order and versions
 
@@ -110,6 +129,7 @@ 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
+  logger, // used for teardown failures when onError is omitted
   allowedCapabilities: ["http", "db"], // reject plugins requesting anything else
   events: eventSink, // receives `plugin:registered`
 });

package/dist/pluginDependencies/versionCheck.core.js

@@ -31,7 +31,11 @@ export class PluginDependencyVersionError extends PluginDependencyError {
     }
 }
 const SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
-const RANGE_PATTERN = /^\s*(\^|~|>=|<=|>|<|=)?\s*(.+?)\s*$/;
+// The input is already trimmed, so the outer `\s*` are unnecessary, and
+// `(\S.*)` rather than `(.+?)\s*$`: `.` matches spaces too, so a lazy group
+// followed by `\s*$` lets the engine split a whitespace run at every
+// position before giving up.
+const RANGE_PATTERN = /^(\^|~|>=|<=|>|<|=)?\s*(\S.*)$/;
 /**
  * Parses a semantic version, returning `undefined` if it is not one.
  */
@@ -63,7 +67,35 @@ export function compareVersions(a, b) {
         return 1;
     if (b.prerelease === undefined)
         return -1;
-    return a.prerelease < b.prerelease ? -1 : 1;
+    return comparePrerelease(a.prerelease, b.prerelease);
+}
+/**
+ * Compares two prerelease strings identifier by identifier, as semver
+ * specifies: numeric identifiers compare numerically and rank below
+ * alphanumeric ones, and a longer identifier list ranks higher when the
+ * shared prefix is equal. A plain string comparison put `alpha.10`
+ * before `alpha.9`.
+ */
+function comparePrerelease(a, b) {
+    const left = a.split(".");
+    const right = b.split(".");
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const x = left[index];
+        const y = right[index];
+        if (x === y)
+            continue;
+        const xNumeric = /^\d+$/.test(x);
+        const yNumeric = /^\d+$/.test(y);
+        if (xNumeric && yNumeric)
+            return Number(x) - Number(y);
+        if (xNumeric)
+            return -1;
+        if (yNumeric)
+            return 1;
+        return x < y ? -1 : 1;
+    }
+    return left.length - right.length;
 }
 /**
  * Tests a version against a range.

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

@@ -0,0 +1,30 @@
+import type { RegisteredPlugin } from "../pluginRegistry/pluginRegistry.core.js";
+/** Outcome of waiting for an abandoned hook. */
+export type AbandonedOutcome = "resolved" | "rejected" | "pending";
+/**
+ * Tracks lifecycle hooks abandoned by `hookTimeout`.
+ *
+ * `Promise.race` cannot cancel the losing hook, so a plugin whose
+ * `start()` timed out kept starting after rollback had already disposed
+ * it, and its `stop()` never ran: the port it went on to open had no
+ * owner. Recording the hook lets teardown wait for it and stop the
+ * plugin once it has actually started.
+ */
+export declare class AbandonedHooks {
+    #private;
+    /** Records a hook that outlived its timeout. */
+    record(registered: RegisteredPlugin, phase: string, hook: Promise<void>): void;
+    /**
+     * Takes the plugin's abandoned hook, if any, and waits up to
+     * `graceMs` for it to settle.
+     *
+     * @returns The phase and outcome, plus the hook itself so a caller can
+     *   still react when it settles after the grace period.
+     */
+    take(registered: RegisteredPlugin, graceMs: number): Promise<{
+        phase: string;
+        outcome: AbandonedOutcome;
+        hook: Promise<void>;
+    } | undefined>;
+}
+//# sourceMappingURL=pluginLifecycle.abandoned.d.ts.map

package/dist/pluginLifecycle/pluginLifecycle.abandoned.js

@@ -0,0 +1,46 @@
+/**
+ * Tracks lifecycle hooks abandoned by `hookTimeout`.
+ *
+ * `Promise.race` cannot cancel the losing hook, so a plugin whose
+ * `start()` timed out kept starting after rollback had already disposed
+ * it, and its `stop()` never ran: the port it went on to open had no
+ * owner. Recording the hook lets teardown wait for it and stop the
+ * plugin once it has actually started.
+ */
+export class AbandonedHooks {
+    #hooks = new Map();
+    /** Records a hook that outlived its timeout. */
+    record(registered, phase, hook) {
+        this.#hooks.set(registered, { phase, hook });
+    }
+    /**
+     * Takes the plugin's abandoned hook, if any, and waits up to
+     * `graceMs` for it to settle.
+     *
+     * @returns The phase and outcome, plus the hook itself so a caller can
+     *   still react when it settles after the grace period.
+     */
+    async take(registered, graceMs) {
+        const entry = this.#hooks.get(registered);
+        if (entry === undefined)
+            return undefined;
+        this.#hooks.delete(registered);
+        let timer;
+        const pending = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("pending"), graceMs);
+            timer.unref?.();
+        });
+        try {
+            const outcome = await Promise.race([
+                entry.hook.then(() => "resolved", () => "rejected"),
+                pending,
+            ]);
+            return { phase: entry.phase, outcome, hook: entry.hook };
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=pluginLifecycle.abandoned.js.map

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

@@ -20,6 +20,7 @@ export interface LifecycleControllerOptions {
  */
 export declare class LifecycleController {
     private readonly options;
+    private readonly abandoned;
     constructor(options?: LifecycleControllerOptions);
     /**
      * Runs a hook under the configured timeout, clearing the timer either
@@ -47,6 +48,14 @@ export declare class LifecycleController {
      * reaches a terminal state so it cannot be disposed twice.
      */
     dispose<TPlugin extends Plugin>(registered: RegisteredPlugin<TPlugin>, context: PluginContext): Promise<void>;
+    /**
+     * Waits (up to `hookTimeout`) for a hook abandoned by a timeout before
+     * the plugin is disposed, and runs `stop()` for a plugin whose timed-out
+     * `start()` went on to succeed. When the hook is still running after
+     * that grace period, `stop()` runs as soon as it does finish, and any
+     * failure is reported through the context logger.
+     */
+    private releaseAbandoned;
     /**
      * Moves a plugin to `failed`, via `stopping` when required.
      */

package/dist/pluginLifecycle/pluginLifecycle.core.js

@@ -1,6 +1,8 @@
 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 { reportPluginFailure } from "./pluginLifecycle.report.js";
 /**
  * Emits a plugin lifecycle event if the context supports events.
  *
@@ -17,7 +19,7 @@ function emitLifecycleEvent(context, eventName, plugin, state, previousState, er
     }
     catch (emitError) {
         queueMicrotask(() => {
-            console.error(`[@zudojs/plugins] Listener for "${eventName}" threw.`, emitError);
+            reportPluginFailure(context.logger, `Listener for "${eventName}" threw.`, emitError, { plugin: plugin.name, event: eventName });
         });
     }
 }
@@ -28,6 +30,7 @@ const MAX_TIMER_DELAY = 2_147_483_647;
  */
 export class LifecycleController {
     options;
+    abandoned = new AbandonedHooks();
     constructor(options = {}) {
         this.options = options;
     }
@@ -35,7 +38,7 @@ export class LifecycleController {
      * Runs a hook under the configured timeout, clearing the timer either
      * way so a completed hook never leaves one armed.
      */
-    async runHook(pluginName, phase, run) {
+    async runHook(pluginName, phase, run, onAbandoned) {
         const timeout = this.options.hookTimeout ?? 0;
         if (timeout <= 0) {
             await run();
@@ -50,9 +53,12 @@ export class LifecycleController {
             await Promise.race([
                 hook,
                 new Promise((_, reject) => {
-                    timer = setTimeout(() => reject(new PluginTimeoutError(pluginName, timeout, {
-                        metadata: { phase },
-                    })), Math.min(timeout, MAX_TIMER_DELAY));
+                    timer = setTimeout(() => {
+                        onAbandoned?.(hook);
+                        reject(new PluginTimeoutError(pluginName, timeout, {
+                            metadata: { phase },
+                        }));
+                    }, Math.min(timeout, MAX_TIMER_DELAY));
                     timer.unref?.();
                 }),
             ]);
@@ -89,7 +95,7 @@ export class LifecycleController {
         registered.setState(transient);
         emitLifecycleEvent(context, startEvent, metadata, transient, from);
         try {
-            await this.runHook(metadata.name, transient, run);
+            await this.runHook(metadata.name, transient, run, (hook) => this.abandoned.record(registered, transient, hook));
             this.ensureTransition(registered, settled);
             registered.setState(settled);
             emitLifecycleEvent(context, endEvent, metadata, settled, transient);
@@ -119,6 +125,7 @@ export class LifecycleController {
         registered.setState("disposing");
         emitLifecycleEvent(context, PLUGIN_EVENTS.DISPOSING, metadata, "disposing", from);
         const errors = [];
+        await this.releaseAbandoned(registered, context, errors);
         // Take the list before running it: a disposable that registers
         // another during teardown must not extend the loop indefinitely.
         const disposables = registered.disposables.splice(0, registered.disposables.length);
@@ -152,6 +159,31 @@ export class LifecycleController {
             throw error;
         }
     }
+    /**
+     * Waits (up to `hookTimeout`) for a hook abandoned by a timeout before
+     * the plugin is disposed, and runs `stop()` for a plugin whose timed-out
+     * `start()` went on to succeed. When the hook is still running after
+     * that grace period, `stop()` runs as soon as it does finish, and any
+     * failure is reported through the context logger.
+     */
+    async releaseAbandoned(registered, context, errors) {
+        const taken = await this.abandoned.take(registered, this.options.hookTimeout ?? 0);
+        if (taken === undefined || taken.phase !== "starting")
+            return;
+        const name = registered.plugin.metadata.name;
+        const stop = () => this.runHook(name, "stopping", () => registered.plugin.stop?.(context));
+        if (taken.outcome === "resolved") {
+            try {
+                await stop();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        else if (taken.outcome === "pending") {
+            void taken.hook.then(() => stop().catch((error) => reportPluginFailure(context.logger, `Plugin "${name}" failed to stop after a late start.`, error, { plugin: name })), () => undefined);
+        }
+    }
     /**
      * Moves a plugin to `failed`, via `stopping` when required.
      */

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

@@ -0,0 +1,16 @@
+import type { PluginLogger } from "../pluginTypes/pluginContext.type.js";
+/**
+ * Reports a plugin failure that has no caller left to throw to.
+ *
+ * Goes through the supplied logger when there is one, so the failure is
+ * structured and redacted like every other log line. Without a logger
+ * it is raised as a process warning (`ZudoPluginWarning`) rather than
+ * written with `console.error`.
+ *
+ * @param logger - The plugin context's (or manager's) logger, if any.
+ * @param message - What failed.
+ * @param error - The underlying error.
+ * @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

@@ -0,0 +1,31 @@
+/**
+ * Reports a plugin failure that has no caller left to throw to.
+ *
+ * Goes through the supplied logger when there is one, so the failure is
+ * structured and redacted like every other log line. Without a logger
+ * it is raised as a process warning (`ZudoPluginWarning`) rather than
+ * written with `console.error`.
+ *
+ * @param logger - The plugin context's (or manager's) logger, if any.
+ * @param message - What failed.
+ * @param error - The underlying error.
+ * @param fields - Extra structured context.
+ */
+export function reportPluginFailure(logger, message, error, fields = {}) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (logger) {
+        try {
+            logger.error(message, { ...fields, error: detail });
+            return;
+        }
+        catch {
+            // A throwing logger falls through to the process warning.
+        }
+    }
+    const emit = globalThis.process?.emitWarning;
+    emit?.(`[@zudojs/plugins] ${message}`, {
+        type: "ZudoPluginWarning",
+        detail,
+    });
+}
+//# sourceMappingURL=pluginLifecycle.report.js.map

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

@@ -1,6 +1,7 @@
 import type { Plugin } from "../pluginTypes/plugin.type.js";
 import type { PluginContext, PluginEvents } from "../pluginTypes/pluginContext.type.js";
 import type { PluginDiagnosticReport } from "../pluginDiagnostics/pluginDiagnostic.core.js";
+import type { PluginLogger } from "../pluginTypes/pluginContext.type.js";
 /**
  * Options for a plugin manager.
  */
@@ -40,6 +41,11 @@ export interface PluginManagerOptions {
      * emitted.
      */
     readonly events?: PluginEvents;
+    /**
+     * Logger for teardown failures when `onError` is not supplied.
+     * Defaults to the logger on the context passed to `start()`/`stop()`.
+     */
+    readonly logger?: PluginLogger;
 }
 /**
  * Plugin manager coordinates registration, dependency resolution, lifecycle, and disposal.
@@ -59,6 +65,8 @@ export declare class PluginManager {
      */
     private startupOrder;
     private starting;
+    /** Logger of the most recent start()/stop() context. */
+    private contextLogger;
     /**
      * Per-plugin context views and their abort handles.
      *

package/dist/pluginManager/pluginManager.core.js

@@ -2,10 +2,11 @@ import { PluginRegistryImpl } from "../pluginRegistry/pluginRegistry.core.js";
 import { DependencyResolver, assertResolutionValid, } from "../pluginDependencies/dependencyResolver.core.js";
 import { assertDependencyVersions } from "../pluginDependencies/versionCheck.core.js";
 import { LifecycleController } from "../pluginLifecycle/pluginLifecycle.core.js";
-import { PluginError, PluginRegistrationError } from "@zudojs/errors";
+import { PluginError, PluginRegistrationError, PluginStateError, } from "@zudojs/errors";
 import { createOwnedPluginContext } from "../pluginIntegration/pluginContext.core.js";
 import { buildDiagnosticReport } from "../pluginDiagnostics/pluginDiagnostic.core.js";
 import { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "../pluginEvents/pluginEvent.core.js";
+import { reportPluginFailure } from "../pluginLifecycle/pluginLifecycle.report.js";
 /**
  * States from which a plugin still owns resources that must be released.
  */
@@ -33,6 +34,8 @@ export class PluginManager {
      */
     startupOrder = [];
     starting = false;
+    /** Logger of the most recent start()/stop() context. */
+    contextLogger;
     /**
      * Per-plugin context views and their abort handles.
      *
@@ -117,6 +120,7 @@ export class PluginManager {
             throw new PluginRegistrationError("Plugin manager start is already in progress.");
         }
         this.starting = true;
+        this.contextLogger = context.logger ?? this.contextLogger;
         try {
             const resolution = this.resolver.resolve(this.toDependencyMap());
             assertResolutionValid(resolution);
@@ -124,10 +128,21 @@ export class PluginManager {
                 assertDependencyVersions(this.plugins);
             }
             this.startupOrder = resolution.ordered;
+            // A disposed plugin has released its resources and the state
+            // machine offers no way back. `start()` used to skip such plugins
+            // silently — so a second `start()` after `stop()` resolved with
+            // nothing running, and after a rolled-back startup it brought up
+            // still-registered dependents on top of disposed dependencies.
+            for (const name of this.startupOrder) {
+                const registered = this.registry.get(name);
+                if (registered?.state === "disposed") {
+                    throw new PluginStateError(name, "disposed", "installing");
+                }
+            }
             try {
                 for (const name of this.startupOrder) {
                     const registered = this.registry.get(name);
-                    if (!registered || registered.state === "disposed")
+                    if (!registered)
                         continue;
                     // Guarded so a restart — where plugins are already installed
                     // and merely stopped — re-runs only the phases it needs.
@@ -137,7 +152,7 @@ export class PluginManager {
                 }
                 for (const name of this.startupOrder) {
                     const registered = this.registry.get(name);
-                    if (!registered || registered.state === "disposed")
+                    if (!registered)
                         continue;
                     if (registered.state === "installed") {
                         await this.lifecycle.initialize(registered, this.contextFor(registered, context));
@@ -145,7 +160,7 @@ export class PluginManager {
                 }
                 for (const name of this.startupOrder) {
                     const registered = this.registry.get(name);
-                    if (!registered || registered.state === "disposed")
+                    if (!registered)
                         continue;
                     if (registered.state === "initialized" ||
                         registered.state === "stopped") {
@@ -170,6 +185,7 @@ export class PluginManager {
      * rather than swallowed.
      */
     async stop(context) {
+        this.contextLogger = context.logger ?? this.contextLogger;
         for (const registered of this.teardownOrder()) {
             if (registered.state !== "started")
                 continue;
@@ -317,7 +333,7 @@ export class PluginManager {
             return;
         }
         queueMicrotask(() => {
-            console.error(`[@zudojs/plugins] Plugin "${pluginName}" failed during teardown.`, error);
+            reportPluginFailure(this.options.logger ?? this.contextLogger, `Plugin "${pluginName}" failed during teardown.`, error, { plugin: pluginName });
         });
     }
     toDependencyMap() {

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/plugins",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Plugin system for extending Zudojs applications with modular capabilities.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -20,9 +24,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0",
-    "@zudojs/types": "1.0.0"
+    "@zudojs/errors": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",