@zudojs/plugins 0.1.0 → 1.0.0

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

@@ -0,0 +1,67 @@
+import type { Plugin } from "../pluginTypes/plugin.type.js";
+import { PluginDependencyError } from "@zudojs/errors";
+/**
+ * A dependency that is registered but whose version does not satisfy the
+ * declared constraint.
+ *
+ * `PluginDependencyError` hardcodes the message "...which is not
+ * registered" and replaces any `metadata` it is handed, so the reason a
+ * version check failed could never reach the operator: every version
+ * mismatch was reported as a missing plugin. This subclass keeps the
+ * type — existing `instanceof PluginDependencyError` handlers still
+ * match — and replaces the message with one that names the requirement,
+ * what is actually registered, and what to do about it.
+ */
+export declare class PluginDependencyVersionError extends PluginDependencyError {
+    /** The plugin that declared the constraint. */
+    readonly requiredBy: string;
+    /** The dependency whose version was checked. */
+    readonly dependencyName: string;
+    /** The declared range, e.g. `^2.0.0`. */
+    readonly required: string;
+    /** The version actually registered, if it declared one. */
+    readonly actual: string | undefined;
+    constructor(requiredBy: string, dependencyName: string, required: string, actual: string | undefined, reason: string);
+}
+/**
+ * A parsed semantic version.
+ *
+ * Exported because {@link parseVersion} returns one and
+ * {@link compareVersions} accepts two: a consumer that cannot name the
+ * type cannot use either function from TypeScript.
+ */
+export interface SemVer {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly prerelease?: string;
+}
+/**
+ * Parses a semantic version, returning `undefined` if it is not one.
+ */
+export declare function parseVersion(version: string): SemVer | undefined;
+/**
+ * Compares two versions. Prerelease versions sort below their release.
+ */
+export declare function compareVersions(a: SemVer, b: SemVer): number;
+/**
+ * Tests a version against a range.
+ *
+ * Supports the range forms a plugin manifest realistically uses:
+ * exact (`1.2.3`), caret (`^1.2.3`), tilde (`~1.2.3`), comparators
+ * (`>=1.2.3`, `>`, `<=`, `<`), and `*` for any version. An
+ * unrecognisable range is reported by the caller rather than silently
+ * passing.
+ */
+export declare function satisfiesVersion(version: string, range: string): boolean | undefined;
+/**
+ * Verifies every declared dependency version constraint.
+ *
+ * A dependency that declares no `version` is unconstrained. A plugin
+ * whose own `metadata.version` is missing cannot be checked, so a
+ * constraint against it is reported rather than quietly passing.
+ *
+ * @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

@@ -0,0 +1,167 @@
+import { PluginDependencyError } from "@zudojs/errors";
+/**
+ * A dependency that is registered but whose version does not satisfy the
+ * declared constraint.
+ *
+ * `PluginDependencyError` hardcodes the message "...which is not
+ * registered" and replaces any `metadata` it is handed, so the reason a
+ * version check failed could never reach the operator: every version
+ * mismatch was reported as a missing plugin. This subclass keeps the
+ * type — existing `instanceof PluginDependencyError` handlers still
+ * match — and replaces the message with one that names the requirement,
+ * what is actually registered, and what to do about it.
+ */
+export class PluginDependencyVersionError extends PluginDependencyError {
+    /** The plugin that declared the constraint. */
+    requiredBy;
+    /** The dependency whose version was checked. */
+    dependencyName;
+    /** The declared range, e.g. `^2.0.0`. */
+    required;
+    /** The version actually registered, if it declared one. */
+    actual;
+    constructor(requiredBy, dependencyName, required, actual, reason) {
+        super(requiredBy, dependencyName);
+        this.name = "PluginDependencyVersionError";
+        this.message = reason;
+        this.requiredBy = requiredBy;
+        this.dependencyName = dependencyName;
+        this.required = required;
+        this.actual = actual;
+    }
+}
+const SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const RANGE_PATTERN = /^\s*(\^|~|>=|<=|>|<|=)?\s*(.+?)\s*$/;
+/**
+ * Parses a semantic version, returning `undefined` if it is not one.
+ */
+export function parseVersion(version) {
+    const match = SEMVER_PATTERN.exec(version.trim());
+    if (!match) {
+        return undefined;
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4],
+    };
+}
+/**
+ * Compares two versions. Prerelease versions sort below their release.
+ */
+export function compareVersions(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    if (a.patch !== b.patch)
+        return a.patch - b.patch;
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (a.prerelease === undefined)
+        return 1;
+    if (b.prerelease === undefined)
+        return -1;
+    return a.prerelease < b.prerelease ? -1 : 1;
+}
+/**
+ * Tests a version against a range.
+ *
+ * Supports the range forms a plugin manifest realistically uses:
+ * exact (`1.2.3`), caret (`^1.2.3`), tilde (`~1.2.3`), comparators
+ * (`>=1.2.3`, `>`, `<=`, `<`), and `*` for any version. An
+ * unrecognisable range is reported by the caller rather than silently
+ * passing.
+ */
+export function satisfiesVersion(version, range) {
+    const trimmedRange = range.trim();
+    if (trimmedRange === "*" || trimmedRange === "" || trimmedRange === "x") {
+        return true;
+    }
+    const actual = parseVersion(version);
+    if (!actual) {
+        return undefined;
+    }
+    const match = RANGE_PATTERN.exec(trimmedRange);
+    if (!match) {
+        return undefined;
+    }
+    const operator = match[1] ?? "=";
+    const expected = parseVersion(match[2] ?? "");
+    if (!expected) {
+        return undefined;
+    }
+    const comparison = compareVersions(actual, expected);
+    switch (operator) {
+        case "=":
+            return comparison === 0;
+        case ">":
+            return comparison > 0;
+        case ">=":
+            return comparison >= 0;
+        case "<":
+            return comparison < 0;
+        case "<=":
+            return comparison <= 0;
+        case "^": {
+            if (comparison < 0)
+                return false;
+            // Caret allows changes that do not modify the left-most non-zero
+            // element, matching npm's semantics for 0.x versions.
+            if (expected.major > 0)
+                return actual.major === expected.major;
+            if (expected.minor > 0)
+                return actual.major === 0 && actual.minor === expected.minor;
+            return (actual.major === 0 &&
+                actual.minor === 0 &&
+                actual.patch === expected.patch);
+        }
+        case "~": {
+            if (comparison < 0)
+                return false;
+            return actual.major === expected.major && actual.minor === expected.minor;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Verifies every declared dependency version constraint.
+ *
+ * A dependency that declares no `version` is unconstrained. A plugin
+ * whose own `metadata.version` is missing cannot be checked, so a
+ * constraint against it is reported rather than quietly passing.
+ *
+ * @throws {PluginDependencyError} on the first unsatisfied constraint.
+ */
+export function assertDependencyVersions(plugins) {
+    for (const [name, plugin] of plugins) {
+        const declared = [
+            ...(plugin.dependencies ?? []),
+            ...(plugin.optionalDependencies ?? []),
+        ];
+        for (const dependency of declared) {
+            if (dependency.version === undefined) {
+                continue;
+            }
+            const target = plugins.get(dependency.name);
+            if (!target) {
+                // Absent optional dependencies are not a version problem.
+                continue;
+            }
+            const actual = target.metadata.version;
+            if (actual === undefined) {
+                throw new PluginDependencyVersionError(name, dependency.name, dependency.version, undefined, `Plugin "${name}" requires "${dependency.name}@${dependency.version}", but "${dependency.name}" declares no version. Add a "version" to that plugin's metadata, or drop the constraint from "${name}".`);
+            }
+            const satisfied = satisfiesVersion(actual, dependency.version);
+            if (satisfied === undefined) {
+                throw new PluginDependencyVersionError(name, dependency.name, dependency.version, actual, `Plugin "${name}" declares an unsupported version range "${dependency.version}" for "${dependency.name}". Supported forms are an exact version (1.2.3), a caret or tilde range (^1.2.3, ~1.2.3), a comparator (>=1.2.3, >, <=, <) or "*".`);
+            }
+            if (!satisfied) {
+                throw new PluginDependencyVersionError(name, dependency.name, dependency.version, actual, `Plugin "${name}" requires "${dependency.name}@${dependency.version}", but version ${actual} is registered. Register a "${dependency.name}" that satisfies ${dependency.version}, relax the constraint on "${name}", or construct the manager with { checkVersions: false }.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=versionCheck.core.js.map

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

@@ -18,6 +18,8 @@ export interface PluginHealth {
 export interface PluginDiagnostic {
     readonly plugin: PluginMetadata;
     readonly state: PluginState;
+    /** Whether the plugin failed at any point in its lifecycle. */
+    readonly failed: boolean;
     readonly health: PluginHealth;
     readonly dependencies: readonly string[];
     readonly optionalDependencies: readonly string[];
@@ -51,5 +53,12 @@ export declare function createUnhealthyHealth(details?: unknown): PluginHealth;
 export declare function buildDiagnosticReport(plugins: Array<{
     readonly plugin: Plugin;
     readonly state: PluginState;
+    /**
+     * Whether the plugin failed at any point. A plugin that failed and
+     * was then disposed during rollback is still a failure worth
+     * reporting, which its current state alone would not show.
+     */
+    readonly failed?: boolean;
+    readonly error?: unknown;
 }>): PluginDiagnosticReport;
 //# sourceMappingURL=pluginDiagnostic.core.d.ts.map

package/dist/pluginDiagnostics/pluginDiagnostic.core.js

@@ -20,21 +20,25 @@ export function createUnhealthyHealth(details) {
  * Builds a diagnostic report from registered plugins.
  */
 export function buildDiagnosticReport(plugins) {
-    const pluginDiagnostics = plugins.map(({ plugin, state }) => ({
-        plugin: plugin.metadata,
-        state,
-        health: state === "started"
-            ? createHealthyHealth()
-            : state === "failed"
-                ? createUnhealthyHealth()
-                : createDegradedHealth(),
-        dependencies: plugin.dependencies?.map((d) => d.name) ?? [],
-        optionalDependencies: plugin.optionalDependencies?.map((d) => d.name) ?? [],
-    }));
+    const pluginDiagnostics = plugins.map(({ plugin, state, failed, error }) => {
+        const hasFailed = failed === true || state === "failed";
+        return {
+            plugin: plugin.metadata,
+            state,
+            failed: hasFailed,
+            health: hasFailed
+                ? createUnhealthyHealth(error instanceof Error ? error.message : error)
+                : state === "started"
+                    ? createHealthyHealth()
+                    : createDegradedHealth(),
+            dependencies: plugin.dependencies?.map((d) => d.name) ?? [],
+            optionalDependencies: plugin.optionalDependencies?.map((d) => d.name) ?? [],
+        };
+    });
     const healthy = pluginDiagnostics.filter((d) => d.health.status === "healthy").length;
     const degraded = pluginDiagnostics.filter((d) => d.health.status === "degraded").length;
     const unhealthy = pluginDiagnostics.filter((d) => d.health.status === "unhealthy").length;
-    const failed = pluginDiagnostics.filter((d) => d.state === "failed").length;
+    const failed = pluginDiagnostics.filter((d) => d.failed).length;
     return {
         plugins: Object.freeze(pluginDiagnostics),
         total: pluginDiagnostics.length,

package/dist/pluginIntegration/index.d.ts

@@ -3,6 +3,7 @@
  *
  * Plugin context factory and integration helpers.
  */
-export { createPluginContext } from "./pluginContext.core.js";
+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

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

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

@@ -1,9 +1,5 @@
 import type { PluginMetadata } from "../pluginTypes/pluginMetadata.type.js";
-import type { PluginContext } from "../pluginTypes/pluginContext.type.js";
-import type { PluginContainer } from "../pluginTypes/pluginContext.type.js";
-import type { PluginConfig } from "../pluginTypes/pluginContext.type.js";
-import type { PluginLogger } from "../pluginTypes/pluginContext.type.js";
-import type { PluginEvents } from "../pluginTypes/pluginContext.type.js";
+import type { PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginDisposable } from "../pluginTypes/pluginContext.type.js";
 /**
  * Options for creating a plugin context.
  */
@@ -12,9 +8,43 @@ export interface CreatePluginContextOptions {
     readonly config?: PluginConfig;
     readonly logger?: PluginLogger;
     readonly events?: PluginEvents;
+    /**
+     * Collection that receives everything the plugin registers for
+     * cleanup. The plugin manager passes the registered plugin's own
+     * array, which is what the lifecycle disposes; without it, anything
+     * registered here would be collected and then never run.
+     */
+    readonly disposables?: PluginDisposable[];
+    /**
+     * Controller whose signal the plugin observes. The manager supplies
+     * one it aborts on shutdown so plugins are told to stop.
+     */
+    readonly abortController?: AbortController;
 }
+/**
+ * A plugin context together with the handles needed to tear it down.
+ */
+export interface OwnedPluginContext {
+    readonly context: PluginContext;
+    /** Everything the plugin registered for cleanup, in registration order. */
+    readonly disposables: PluginDisposable[];
+    /** Aborts `context.signal`. */
+    readonly abort: (reason?: unknown) => void;
+}
+/**
+ * Creates a plugin context and returns it with its teardown handles.
+ *
+ * The disposables array and the abort function are the two capabilities
+ * a context cannot expose to its own consumer but its owner needs, so
+ * they are returned alongside rather than trapped in the closure.
+ */
+export declare function createOwnedPluginContext(plugin: PluginMetadata, options?: CreatePluginContextOptions): OwnedPluginContext;
 /**
  * Creates a plugin context for testing and basic usage.
+ *
+ * Pass `options.disposables` to reach what the plugin registers;
+ * otherwise use {@link createOwnedPluginContext}, which returns the
+ * 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

@@ -1,10 +1,14 @@
 /**
- * Creates a plugin context for testing and basic usage.
+ * Creates a plugin context and returns it with its teardown handles.
+ *
+ * The disposables array and the abort function are the two capabilities
+ * a context cannot expose to its own consumer but its owner needs, so
+ * they are returned alongside rather than trapped in the closure.
  */
-export function createPluginContext(plugin, options = {}) {
-    const abortController = new AbortController();
-    const disposables = [];
-    return {
+export function createOwnedPluginContext(plugin, options = {}) {
+    const abortController = options.abortController ?? new AbortController();
+    const disposables = options.disposables ?? [];
+    const context = {
         plugin,
         signal: abortController.signal,
         container: options.container,
@@ -18,5 +22,24 @@ export function createPluginContext(plugin, options = {}) {
             disposables.push(disposable);
         },
     };
+    return {
+        context,
+        disposables,
+        abort: (reason) => {
+            if (!abortController.signal.aborted) {
+                abortController.abort(reason);
+            }
+        },
+    };
+}
+/**
+ * Creates a plugin context for testing and basic usage.
+ *
+ * Pass `options.disposables` to reach what the plugin registers;
+ * otherwise use {@link createOwnedPluginContext}, which returns the
+ * collection and the abort handle with the context.
+ */
+export function createPluginContext(plugin, options = {}) {
+    return createOwnedPluginContext(plugin, options).context;
 }
 //# sourceMappingURL=pluginContext.core.js.map

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

@@ -1,15 +1,57 @@
 import type { Plugin } from "../pluginTypes/plugin.type.js";
 import type { PluginContext } from "../pluginTypes/pluginContext.type.js";
 import type { RegisteredPlugin } from "../pluginRegistry/pluginRegistry.core.js";
+/**
+ * Options controlling lifecycle execution.
+ */
+export interface LifecycleControllerOptions {
+    /**
+     * Maximum time a single lifecycle hook may run, in milliseconds.
+     *
+     * Defaults to `0` (unbounded), preserving existing behaviour. Set a
+     * value to bound boot and shutdown: without one, a plugin whose
+     * `start()` never settles hangs the whole application with no
+     * diagnostic.
+     */
+    readonly hookTimeout?: number;
+}
 /**
  * Executes plugin lifecycle phases with state management and event emission.
  */
 export declare class LifecycleController {
+    private readonly options;
+    constructor(options?: LifecycleControllerOptions);
+    /**
+     * Runs a hook under the configured timeout, clearing the timer either
+     * way so a completed hook never leaves one armed.
+     */
+    private runHook;
     install<TPlugin extends Plugin>(registered: RegisteredPlugin<TPlugin>, context: PluginContext): Promise<void>;
     initialize<TPlugin extends Plugin>(registered: RegisteredPlugin<TPlugin>, context: PluginContext): Promise<void>;
     start<TPlugin extends Plugin>(registered: RegisteredPlugin<TPlugin>, context: PluginContext): Promise<void>;
     stop<TPlugin extends Plugin>(registered: RegisteredPlugin<TPlugin>, context: PluginContext): Promise<void>;
+    /**
+     * Runs one lifecycle phase, moving through its transient state.
+     *
+     * On failure the plugin moves to `failed` through the state machine
+     * rather than around it, so the recorded state is always one the
+     * machine actually permits.
+     */
+    private runPhase;
+    /**
+     * Disposes a plugin and everything it registered for cleanup.
+     *
+     * Disposables run in reverse registration order — the mirror of how
+     * they were acquired — and the list is emptied so a second dispose
+     * cannot run them again. Every failure is collected; the plugin still
+     * reaches a terminal state so it cannot be disposed twice.
+     */
     dispose<TPlugin extends Plugin>(registered: RegisteredPlugin<TPlugin>, context: PluginContext): Promise<void>;
+    /**
+     * Moves a plugin to `failed`, via `stopping` when required.
+     */
+    private transitionToFailed;
+    private canTransition;
     private ensureTransition;
 }
 //# sourceMappingURL=pluginLifecycle.core.d.ts.map