@zudojs/plugins 0.1.0 → 1.1.0

package/dist/pluginManager/pluginManager.core.js

@@ -1,9 +1,20 @@
 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 { PluginAlreadyRegisteredError, PluginDependencyCycleError, PluginDependencyError, PluginInitializationError, PluginNotFoundError, PluginRegistrationError, } from "@zudojs/errors";
-import { PLUGIN_EVENTS } from "../pluginEvents/pluginEvent.core.js";
-import { buildDiagnosticReport, createHealthyHealth, createUnhealthyHealth, } from "../pluginDiagnostics/pluginDiagnostic.core.js";
+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";
+/**
+ * States from which a plugin still owns resources that must be released.
+ */
+const DISPOSABLE_STATES = new Set([
+    "installed",
+    "initialized",
+    "stopped",
+    "failed",
+]);
 /**
  * Plugin manager coordinates registration, dependency resolution, lifecycle, and disposal.
  */
@@ -12,19 +23,78 @@ export class PluginManager {
     resolver;
     lifecycle;
     plugins = new Map();
-    constructor() {
+    options;
+    /**
+     * Dependency-first order from the last successful resolution.
+     *
+     * Shutdown reverses this rather than registration order: tearing down
+     * in registration order destroys a dependency while its dependents are
+     * still using it.
+     */
+    startupOrder = [];
+    starting = false;
+    /**
+     * Per-plugin context views and their abort handles.
+     *
+     * Each plugin gets a context whose `onDispose` and
+     * `registerDisposable` write to that plugin's own disposables list —
+     * the list the lifecycle actually drains — and whose `signal` this
+     * manager aborts on shutdown.
+     */
+    contexts = new Map();
+    constructor(options = {}) {
         this.registry = new PluginRegistryImpl();
         this.resolver = new DependencyResolver();
-        this.lifecycle = new LifecycleController();
+        this.lifecycle = new LifecycleController(options.hookTimeout !== undefined
+            ? { hookTimeout: options.hookTimeout }
+            : {});
+        this.options = options;
     }
-    register(plugin) {
+    /**
+     * Registers a plugin.
+     *
+     * @throws {PluginAlreadyRegisteredError} when the name is taken, so
+     * callers can implement idempotent registration.
+     */
+    register(plugin, options) {
+        if (typeof plugin?.metadata?.name !== "string" ||
+            plugin.metadata.name.length === 0) {
+            throw new PluginRegistrationError("Plugin metadata must include a non-empty name.");
+        }
+        const allowed = this.options.allowedCapabilities;
+        if (allowed) {
+            const requested = plugin.metadata.capabilities ?? [];
+            const denied = requested.filter((capability) => !allowed.includes(capability));
+            if (denied.length > 0) {
+                throw new PluginRegistrationError(`Plugin "${plugin.metadata.name}" requests capabilities that are not granted: ${denied.join(", ")}.`, plugin.metadata.name);
+            }
+        }
         try {
-            this.registry.register(plugin);
+            this.registry.register(plugin, options);
             this.plugins.set(plugin.metadata.name, plugin);
+            this.emitRegistered(plugin);
         }
         catch (error) {
-            throw new PluginRegistrationError(error.message, plugin.metadata.name);
+            // Typed plugin errors already say what went wrong and let callers
+            // branch on the cause; only unexpected failures are wrapped.
+            if (error instanceof PluginError) {
+                throw error;
+            }
+            throw new PluginRegistrationError(error instanceof Error ? error.message : String(error), plugin.metadata.name);
+        }
+    }
+    /**
+     * Removes a plugin that has not been started.
+     *
+     * Keeps the manager's own view in step with the registry; leaving a
+     * removed plugin in `plugins` would keep it in dependency resolution.
+     */
+    unregister(name) {
+        const removed = this.registry.remove(name);
+        if (removed) {
+            this.plugins.delete(name);
         }
+        return removed;
     }
     get(name) {
         return this.registry.get(name)?.plugin;
@@ -35,66 +105,231 @@ export class PluginManager {
     list() {
         return this.registry.list().map((r) => r.plugin);
     }
+    /**
+     * Installs, initializes and starts every plugin in dependency order.
+     *
+     * A failure anywhere rolls back: everything already brought up is
+     * stopped and disposed before the error is rethrown, so an aborted
+     * startup does not strand resources with no route to release them.
+     */
     async start(context) {
-        const resolution = this.resolver.resolve(this.toDependencyMap());
-        assertResolutionValid(resolution);
-        const ordered = resolution.ordered;
-        for (const name of ordered) {
-            const registered = this.registry.get(name);
-            if (!registered || registered.state === "disposed") {
-                continue;
+        if (this.starting) {
+            throw new PluginRegistrationError("Plugin manager start is already in progress.");
+        }
+        this.starting = true;
+        try {
+            const resolution = this.resolver.resolve(this.toDependencyMap());
+            assertResolutionValid(resolution);
+            if (this.options.checkVersions ?? true) {
+                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)
+                        continue;
+                    // Guarded so a restart — where plugins are already installed
+                    // and merely stopped — re-runs only the phases it needs.
+                    if (registered.state === "registered") {
+                        await this.lifecycle.install(registered, this.contextFor(registered, context));
+                    }
+                }
+                for (const name of this.startupOrder) {
+                    const registered = this.registry.get(name);
+                    if (!registered)
+                        continue;
+                    if (registered.state === "installed") {
+                        await this.lifecycle.initialize(registered, this.contextFor(registered, context));
+                    }
+                }
+                for (const name of this.startupOrder) {
+                    const registered = this.registry.get(name);
+                    if (!registered)
+                        continue;
+                    if (registered.state === "initialized" ||
+                        registered.state === "stopped") {
+                        await this.lifecycle.start(registered, this.contextFor(registered, context));
+                    }
+                }
+            }
+            catch (error) {
+                await this.rollback(context);
+                throw error;
             }
-            await this.lifecycle.install(registered, context);
         }
-        for (const name of ordered) {
-            const registered = this.registry.get(name);
-            if (!registered || registered.state === "disposed") {
+        finally {
+            this.starting = false;
+        }
+    }
+    /**
+     * Stops and disposes every plugin, in reverse dependency order.
+     *
+     * Teardown continues past a failing plugin so one bad `stop` cannot
+     * strand the rest, and every failure is reported through `onError`
+     * rather than swallowed.
+     */
+    async stop(context) {
+        for (const registered of this.teardownOrder()) {
+            if (registered.state !== "started")
                 continue;
+            try {
+                await this.lifecycle.stop(registered, this.contextFor(registered, context));
             }
-            if (registered.state === "installed") {
-                await this.lifecycle.initialize(registered, context);
+            catch (error) {
+                this.report(error, registered.plugin.metadata.name);
             }
         }
-        for (const name of ordered) {
-            const registered = this.registry.get(name);
-            if (!registered || registered.state === "disposed") {
+        for (const registered of this.teardownOrder()) {
+            // Anything that still holds resources is disposed, including
+            // plugins that were installed or initialized but never started
+            // because an earlier plugin failed.
+            if (!DISPOSABLE_STATES.has(registered.state))
                 continue;
+            const name = registered.plugin.metadata.name;
+            try {
+                // Abort first so work the plugin started sees the shutdown
+                // before its disposables are released underneath it.
+                this.abortContext(name);
+                await this.lifecycle.dispose(registered, this.contextFor(registered, context));
+            }
+            catch (error) {
+                this.report(error, name);
             }
-            if (registered.state === "initialized") {
-                await this.lifecycle.start(registered, context);
+            finally {
+                this.contexts.delete(name);
             }
         }
     }
-    async stop(context) {
-        const plugins = this.registry.list();
-        const reversed = [...plugins].reverse();
-        for (const registered of reversed) {
+    diagnostics() {
+        const plugins = this.registry.list().map((registered) => ({
+            plugin: registered.plugin,
+            state: registered.state,
+            failed: registered.failed,
+            error: registered.error,
+        }));
+        return buildDiagnosticReport(plugins);
+    }
+    /**
+     * Tears down everything brought up by a failed startup.
+     */
+    async rollback(context) {
+        for (const registered of this.teardownOrder()) {
             if (registered.state === "started") {
                 try {
-                    await this.lifecycle.stop(registered, context);
+                    await this.lifecycle.stop(registered, this.contextFor(registered, context));
                 }
-                catch {
-                    continue;
+                catch (error) {
+                    this.report(error, registered.plugin.metadata.name);
                 }
             }
         }
-        for (const registered of reversed) {
-            if (registered.state === "stopped" || registered.state === "failed") {
-                try {
-                    await this.lifecycle.dispose(registered, context);
-                }
-                catch {
-                    continue;
-                }
+        for (const registered of this.teardownOrder()) {
+            if (!DISPOSABLE_STATES.has(registered.state))
+                continue;
+            const name = registered.plugin.metadata.name;
+            try {
+                this.abortContext(name);
+                await this.lifecycle.dispose(registered, this.contextFor(registered, context));
+            }
+            catch (error) {
+                this.report(error, name);
+            }
+            finally {
+                this.contexts.delete(name);
             }
         }
     }
-    diagnostics() {
-        const plugins = this.registry.list().map((registered) => ({
-            plugin: registered.plugin,
-            state: registered.state,
-        }));
-        return buildDiagnosticReport(plugins);
+    /**
+     * Registered plugins in reverse dependency order.
+     *
+     * Falls back to reverse registration order for plugins registered
+     * after the last resolution, which is the best available guess.
+     */
+    teardownOrder() {
+        const seen = new Set();
+        const ordered = [];
+        for (let i = this.startupOrder.length - 1; i >= 0; i -= 1) {
+            const name = this.startupOrder[i];
+            const registered = this.registry.get(name);
+            if (registered) {
+                seen.add(name);
+                ordered.push(registered);
+            }
+        }
+        const remaining = this.registry
+            .list()
+            .filter((registered) => !seen.has(registered.plugin.metadata.name))
+            .reverse();
+        return [...ordered, ...remaining];
+    }
+    /**
+     * Returns the plugin's own context view, creating it on first use.
+     *
+     * The base context supplies the shared services; only the identity,
+     * the disposables collection and the abort signal are per-plugin.
+     */
+    contextFor(registered, base) {
+        const name = registered.plugin.metadata.name;
+        const existing = this.contexts.get(name);
+        if (existing) {
+            return existing.context;
+        }
+        const owned = createOwnedPluginContext(registered.plugin.metadata, {
+            container: base.container,
+            config: base.config,
+            logger: base.logger,
+            events: base.events,
+            disposables: registered.disposables,
+        });
+        this.contexts.set(name, { context: owned.context, abort: owned.abort });
+        return owned.context;
+    }
+    /**
+     * Aborts a plugin's signal, keeping the context available.
+     *
+     * The entry stays so `dispose` still receives the same — now aborted —
+     * context; removing it here would hand the dispose hook a fresh
+     * context whose signal had never fired.
+     */
+    abortContext(name, reason) {
+        this.contexts.get(name)?.abort(reason);
+    }
+    /**
+     * Emits `plugin:registered`, containing a throwing subscriber so a bad
+     * listener cannot fail the registration that triggered it.
+     */
+    emitRegistered(plugin) {
+        const events = this.options.events;
+        if (!events) {
+            return;
+        }
+        try {
+            events.emit(PLUGIN_EVENTS.REGISTERED, createPluginLifecycleEvent(plugin.metadata, "registered"));
+        }
+        catch (error) {
+            this.report(error, plugin.metadata.name);
+        }
+    }
+    report(error, pluginName) {
+        if (this.options.onError) {
+            this.options.onError(error, pluginName);
+            return;
+        }
+        queueMicrotask(() => {
+            console.error(`[@zudojs/plugins] Plugin "${pluginName}" failed during teardown.`, error);
+        });
     }
     toDependencyMap() {
         const map = new Map();

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

@@ -1,5 +1,6 @@
 import type { Plugin } from "../pluginTypes/plugin.type.js";
 import type { PluginState } from "../pluginTypes/pluginState.type.js";
+import type { PluginDisposable } from "../pluginTypes/pluginContext.type.js";
 /**
  * Internal representation of a registered plugin.
  */
@@ -7,13 +8,21 @@ export interface RegisteredPlugin<TPlugin extends Plugin = Plugin> {
     readonly plugin: TPlugin;
     state: PluginState;
     readonly options?: unknown;
-    readonly disposables: Array<{
-        dispose(): void | Promise<void>;
-    }>;
-    registerDisposable(disposable: {
-        dispose(): void | Promise<void>;
-    }): void;
+    readonly disposables: PluginDisposable[];
+    /**
+     * Whether this plugin failed at any point in its lifecycle.
+     *
+     * Tracked separately from `state` because a failed plugin is disposed
+     * during rollback, which would otherwise erase every trace of the
+     * failure from diagnostics.
+     */
+    failed: boolean;
+    /** The error that caused the failure, if any. */
+    error?: unknown;
+    registerDisposable(disposable: PluginDisposable): void;
     setState(state: PluginState): void;
+    /** Records a lifecycle failure. */
+    setError(error: unknown): void;
 }
 /**
  * Plugin registry interface.

package/dist/pluginRegistry/pluginRegistry.core.js

@@ -1,4 +1,4 @@
-import { PluginAlreadyRegisteredError, PluginNotFoundError, PluginStateError, } from "@zudojs/errors";
+import { PluginAlreadyRegisteredError, PluginStateError } from "@zudojs/errors";
 /**
  * Default plugin registry implementation.
  */
@@ -15,12 +15,17 @@ export class PluginRegistryImpl {
             state: "registered",
             options,
             disposables,
+            failed: false,
             registerDisposable(disposable) {
                 disposables.push(disposable);
             },
             setState(state) {
                 registered.state = state;
             },
+            setError(error) {
+                registered.failed = true;
+                registered.error = error;
+            },
         };
         this.plugins.set(name, registered);
     }

package/dist/pluginTypes/index.d.ts

@@ -6,7 +6,7 @@
 export type { PluginState } from "./pluginState.type.js";
 export type { PluginMetadata } from "./pluginMetadata.type.js";
 export type { PluginDependency } from "./pluginDependency.type.js";
-export type { PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, } from "./pluginContext.type.js";
+export type { PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginDisposable, } from "./pluginContext.type.js";
 export type { Plugin } from "./plugin.type.js";
 export type { PluginErrorOptions } from "@zudojs/errors";
 //# sourceMappingURL=index.d.ts.map

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

@@ -27,6 +27,12 @@ export interface PluginEvents {
     off(event: string, handler: (event: unknown) => void): void;
     emit(event: string, payload: unknown): void;
 }
+/**
+ * Something a plugin registers so the manager releases it on shutdown.
+ */
+export interface PluginDisposable {
+    dispose(): void | Promise<void>;
+}
 /**
  * Controlled context provided to plugins during lifecycle operations.
  */
@@ -36,10 +42,12 @@ export interface PluginContext {
     readonly config?: PluginConfig;
     readonly logger?: PluginLogger;
     readonly events?: PluginEvents;
+    /**
+     * Aborted when the plugin system shuts down, so long-lived work
+     * started by the plugin can stop.
+     */
     readonly signal: AbortSignal;
     onDispose(handler: () => void | Promise<void>): void;
-    registerDisposable(disposable: {
-        dispose(): void | Promise<void>;
-    }): void;
+    registerDisposable(disposable: PluginDisposable): void;
 }
 //# sourceMappingURL=pluginContext.type.d.ts.map

package/dist/pluginTypes/pluginState.type.js

@@ -2,11 +2,14 @@
  * Valid state transitions for the plugin state machine.
  */
 export const VALID_STATE_TRANSITIONS = {
-    registered: ["installing"],
+    registered: ["installing", "disposing"],
     installing: ["installed", "failed"],
-    installed: ["initializing", "stopping"],
+    // A plugin that installed but never started still holds resources, so
+    // it must have a route to disposal; without one an aborted startup
+    // stranded it permanently.
+    installed: ["initializing", "stopping", "disposing", "failed"],
     initializing: ["initialized", "failed"],
-    initialized: ["starting", "stopping"],
+    initialized: ["starting", "stopping", "disposing", "failed"],
     starting: ["started", "failed"],
     started: ["stopping"],
     stopping: ["stopped", "failed"],

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/plugins",
-  "version": "0.1.0",
+  "version": "1.1.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",
@@ -14,23 +18,19 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/constants": "0.1.0",
-    "@zudojs/types": "0.1.0"
+    "@zudojs/errors": "1.0.1",
+    "@zudojs/constants": "1.0.1",
+    "@zudojs/types": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "engines": {
@@ -45,8 +45,19 @@
     "extensions"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/plugins"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}