@ayepi/plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+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

@@ -0,0 +1,106 @@
+# @ayepi/plugin
+
+A plugin system for [`@ayepi/core`](../core). Compose an API from independent
+**plugins** — each a frontend-safe spec, its server implementation, an exported
+**state** service, lifecycle hooks, and a `requires` list — and install/uninstall
+them **into a running server**.
+
+```sh
+pnpm add @ayepi/plugin @ayepi/core zod
+```
+
+## What a plugin is
+
+A plugin bundles five things:
+
+- **`spec`** — the frontend-safe API contract (a normal `spec()`).
+- **`.handlers` / `.middleware`** — its handlers + middleware bindings (chained on the builder).
+- **`state`** — a service object (functions + data) that *dependent* plugins call
+  directly, with no HTTP and no middleware (the "better private functions").
+- **`.lifecycle`** — `up` / `down` (drain) / `stop` (teardown) hooks.
+- **`requires`** — the plugins it depends on, available in its **context**.
+
+`plugin({ name, requires, spec, state })` returns a **builder**; chain ctx-aware
+`.middleware` / `.handlers` / `.lifecycle` (mirroring core's `implement()`). Each
+callback receives a dependency **context** (`ctx`): `ctx.deps.<name>` exposes each
+required plugin's `state` service, a typed in-process `call` for its endpoints, and an
+`emit` for its events; `ctx.state` is this plugin's own computed state; `ctx.emit`
+publishes its own events. So a plugin uses its dependencies with just a data payload —
+no manual context threading.
+
+## Quick start
+
+```ts
+import { spec, endpoint, server } from '@ayepi/core';
+import { plugin, createPluginHost } from '@ayepi/plugin';
+import { z } from 'zod';
+
+const authSpec = spec({ endpoints: { login: endpoint({ body: z.object({ user: z.string() }), response: z.object({ token: z.string() }) }) } });
+const auth = plugin({
+  name: 'auth',
+  spec: authSpec,
+  state: () => ({ verify: (t: string) => (t.startsWith('tok-') ? t.slice(4) : null) }),
+}).handlers(() => ({ login: ({ data }) => ({ token: `tok-${data.user}` }) }));
+
+const notesSpec = spec({ endpoints: { add: endpoint({ body: z.object({ token: z.string(), text: z.string() }), response: z.object({ ok: z.boolean() }) }) } });
+const notes = plugin({
+  name: 'notes',
+  requires: [auth] as const,
+  spec: notesSpec,
+}).handlers((ctx) => ({
+  add: ({ data }) => ({ ok: ctx.deps.auth.state.verify(data.token) !== null }), // ← dep's state service
+}));
+
+const app = server(spec({ endpoints: {} }), []); // boot (nearly) empty
+const host = createPluginHost(app);
+await host.install(auth);   // base plugin
+await host.install(notes);  // requires auth → installed after it
+// ... app.fetch(...) now serves /login and /add — added while the server is live ...
+await host.shutdown();      // tears every plugin down in dependency order
+```
+
+## How it works
+
+It builds on three core primitives:
+
+- **`Server.install` / `uninstall`** — hot-mount/unmount a spec + builders on a live
+  server (routes, events, middleware, manifest, docs all refresh).
+- **`localClient(app, spec)`** — the in-process, no-serialization caller behind
+  `ctx.deps.<dep>.call`.
+- **`provide`** — inject typed values onto context.
+
+The host installs in dependency order, builds each plugin's context from the
+registry, runs `lifecycle.up`, then mounts it. `uninstall` reverses that (drain →
+remove → teardown) and **refuses while a live dependent remains**.
+
+## Handlers in other files
+
+For larger codebases, capture the builder in its own `const` and type handlers/
+middleware in other files against `typeof builder` (non-circular, since the builder's
+config carries no implementation), then fold them in with the chain methods:
+
+```ts
+// notes.ts
+export const notesDef = plugin({ name: 'notes', requires: [auth] as const, spec, state });
+import { addNote } from './notes.handlers';
+export const notes = notesDef.handlers((ctx) => ({ addNote: addNote(ctx) }));
+
+// notes.handlers.ts
+import type { notesDef } from './notes'; // type-only — no runtime cycle
+export const addNote: PluginHandlers<typeof notesDef>['addNote'] =
+  (ctx) => ({ data }) => ctx.deps.auth.state.verify(data.token) ? ctx.state.add(…) : reject(401, 'UNAUTHORIZED');
+```
+
+See **[`ayepi-plugin.md`](./ayepi-plugin.md)** for the full reference, and
+[`examples/08-plugins`](../../examples/08-plugins) for a runnable demo (auth → notes
+→ stats, with hot uninstall/reinstall).
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-plugin.md`](./ayepi-plugin.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/plugin) and are **not** shipped in the npm tarball.
+

package/dist/index.cjs

@@ -0,0 +1,167 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _ayepi_core = require("@ayepi/core");
+//#region src/plugin.ts
+/** Build an immutable builder over the given state. */
+function makeBuilder(s) {
+	return {
+		name: s.name,
+		spec: s.spec,
+		requires: s.requires,
+		middleware(defOrBound, impl) {
+			const entry = impl ? {
+				def: defOrBound,
+				implFactory: impl
+			} : { bound: defOrBound };
+			return makeBuilder({
+				...s,
+				mws: [...s.mws, entry]
+			});
+		},
+		handlers(factory) {
+			return makeBuilder({
+				...s,
+				handlerFactories: [...s.handlerFactories, factory]
+			});
+		},
+		lifecycle(factory) {
+			return makeBuilder({
+				...s,
+				lifecycleFactory: factory
+			});
+		},
+		__state: (ctx) => s.stateFactory ? s.stateFactory(ctx) : void 0,
+		__implement: (ctx) => {
+			let b = (0, _ayepi_core.implement)(s.spec);
+			for (const mw of s.mws) b = mw.bound ? b.middleware(mw.bound) : b.middleware(mw.def, mw.implFactory(ctx));
+			const bag = {};
+			for (const hf of s.handlerFactories) Object.assign(bag, hf(ctx));
+			return b.handlers(bag);
+		},
+		__lifecycle: (ctx) => s.lifecycleFactory ? s.lifecycleFactory(ctx) : {}
+	};
+}
+/**
+* Create a plugin **builder** from its config. The builder is inert until a
+* {@link createPluginHost | host} installs it — at which point its `state` is computed,
+* its `lifecycle.up` runs, and its `spec` + handlers are mounted live. Chain
+* `.middleware`/`.handlers`/`.lifecycle` to add the implementation.
+*
+* @typeParam Name  - inferred from `config.name`.
+* @typeParam Spec  - inferred from `config.spec`.
+* @typeParam State - inferred from `config.state`'s return (`undefined` if omitted).
+* @typeParam Deps  - inferred from `config.requires`.
+*/
+function plugin(config) {
+	return makeBuilder({
+		name: config.name,
+		spec: config.spec,
+		requires: config.requires ?? [],
+		stateFactory: config.state,
+		mws: [],
+		handlerFactories: []
+	});
+}
+//#endregion
+//#region src/host.ts
+/**
+* Create a {@link PluginHost} over a running {@link Server} (which may start nearly
+* empty — e.g. `server(spec({ endpoints: {} }), [])` — or carry a core spec).
+*
+* @example
+* ```ts
+* const app = server(spec({ endpoints: {} }), []);
+* const host = createPluginHost(app);
+* await host.install(auth);     // a base plugin
+* await host.install(users);    // requires auth → installed after it
+* // ... app.fetch(...) now serves both plugins' endpoints ...
+* await host.shutdown();
+* ```
+*/
+function createPluginHost(app, opts = {}) {
+	const registry = /* @__PURE__ */ new Map();
+	const installSpec = app.install;
+	/** Report a swallowed teardown error (best-effort — a throwing `onError` is itself ignored). */
+	const report = (err, phase, plugin) => {
+		try {
+			opts.onError?.(err, phase, plugin);
+		} catch {}
+	};
+	/** Run a lifecycle hook so its failure is isolated — reported, not thrown — so teardown of the rest continues. */
+	const safe = async (hook, phase, plugin) => {
+		try {
+			await hook?.();
+		} catch (err) {
+			report(err, phase, plugin);
+		}
+	};
+	const liveDependents = (name) => [...registry.values()].filter((e) => e.plugin.requires.some((d) => d.name === name)).map((e) => e.plugin.name);
+	/** Assemble the `{ deps, emit }` base context for a plugin from the registry. */
+	function buildBaseCtx(plugin) {
+		const deps = {};
+		for (const dep of plugin.requires) {
+			const entry = registry.get(dep.name);
+			deps[dep.name] = {
+				state: entry.state,
+				call: (0, _ayepi_core.localClient)(app, dep.spec).call,
+				emit: app.emit
+			};
+		}
+		return {
+			deps,
+			emit: app.emit
+		};
+	}
+	async function install(plugin) {
+		if (registry.has(plugin.name)) throw new Error(`plugin "${plugin.name}" is already installed`);
+		for (const dep of plugin.requires) if (!registry.has(dep.name)) throw new Error(`plugin "${plugin.name}" requires "${dep.name}", which is not installed`);
+		const base = buildBaseCtx(plugin);
+		const internals = plugin;
+		const state = internals.__state(base);
+		const ctx = {
+			...base,
+			state
+		};
+		const builder = internals.__implement(ctx);
+		const lc = internals.__lifecycle(ctx);
+		await lc.up?.();
+		let handle;
+		try {
+			handle = installSpec(plugin.spec, [builder]);
+		} catch (err) {
+			await safe(() => lc.stop?.(), "stop", plugin.name);
+			throw err;
+		}
+		registry.set(plugin.name, {
+			plugin,
+			state,
+			lc,
+			handle
+		});
+	}
+	async function uninstall(name) {
+		const entry = registry.get(name);
+		if (!entry) throw new Error(`plugin "${name}" is not installed`);
+		const dependents = liveDependents(name);
+		if (dependents.length > 0) throw new Error(`cannot uninstall "${name}": still required by ${dependents.map((d) => `"${d}"`).join(", ")}`);
+		await safe(() => entry.lc.down?.(), "down", name);
+		try {
+			app.uninstall(entry.handle);
+		} catch (err) {
+			report(err, "remove", name);
+		}
+		await safe(() => entry.lc.stop?.(), "stop", name);
+		registry.delete(name);
+	}
+	async function shutdown() {
+		while (registry.size > 0) await uninstall([...registry.keys()].find((n) => liveDependents(n).length === 0));
+	}
+	return {
+		install,
+		uninstall,
+		installed: () => [...registry.keys()],
+		shutdown
+	};
+}
+//#endregion
+exports.createPluginHost = createPluginHost;
+exports.plugin = plugin;

package/dist/index.d.cts

@@ -0,0 +1,179 @@
+import { AnyEndpoint, AnyMiddleware, AnySpec, BoundMiddleware, EmitFn, HandlerFor, ImplFor, LocalClient, Server } from "@ayepi/core";
+
+//#region src/plugin.d.ts
+
+/** Loosest internal function type — replaces the banned `Function`. */
+type AnyFn = (...args: never[]) => unknown;
+/** Lifecycle hooks a plugin runs around install/uninstall, in dependency order. */
+interface Lifecycle {
+  /** Start work — runs after the plugin's deps are up, before its endpoints serve. */
+  readonly up?: () => void | Promise<void>;
+  /** Drain — the pre-stop phase (stop accepting work, finish in-flight). */
+  readonly down?: () => void | Promise<void>;
+  /** Teardown — the post-stop phase (close resources). */
+  readonly stop?: () => void | Promise<void>;
+}
+/**
+ * The methods-free structural base every plugin builder satisfies — what the `*Of` /
+ * `PluginHandlers` / `CtxOf` helpers match on. Keeping `AnyPlugin` to this shape (no
+ * chain methods) is essential: comparing full builders would expand `.middleware`'s
+ * `ImplFor<M>` into `ImplFor<AnyMiddleware>` and recurse infinitely.
+ */
+interface PluginShape<Name extends string, Spec extends AnySpec, State, Deps extends readonly AnyPlugin[]> {
+  readonly name: Name;
+  readonly spec: Spec;
+  readonly requires: Deps;
+  /** @internal phantom carrier of the state-service type. */
+  readonly __state?: State;
+}
+/** Any plugin, erased — the constraint for `requires` lists and the host registry. */
+type AnyPlugin = PluginShape<string, AnySpec, unknown, readonly AnyPlugin[]>;
+/** Extract a plugin's exported state-service type. */
+type StateOf<P> = P extends {
+  readonly __state?: infer S;
+} ? S : never;
+/** Extract a plugin's spec. */
+type SpecOf<P> = P extends {
+  readonly spec: infer Sp extends AnySpec;
+} ? Sp : never;
+/** Extract a plugin's name. */
+type NameOf<P> = P extends {
+  readonly name: infer N extends string;
+} ? N : never;
+/** Extract a plugin's `requires` tuple. */
+type DepsOf<P> = P extends {
+  readonly requires: infer D extends readonly AnyPlugin[];
+} ? D : never;
+/** The handle a plugin gets for one of its dependencies. */
+interface DepHandle<P extends AnyPlugin> {
+  /** The dependency's exported **state** service (its functions + data). */
+  readonly state: StateOf<P>;
+  /** Call one of the dependency's endpoints in-process, with just a data payload. */
+  readonly call: LocalClient<SpecOf<P>>['call'];
+  /** Emit one of the dependency's events. */
+  readonly emit: EmitFn<SpecOf<P>>;
+}
+/** The `deps` record on a plugin context — keyed by each required plugin's name. */
+type DepsRecord<Deps extends readonly AnyPlugin[]> = { readonly [P in Deps[number] as NameOf<P>]: DepHandle<P> };
+/** The context passed to a plugin's `state` builder — its dependencies + an `emit` for its own events. */
+interface DepsCtx<Deps extends readonly AnyPlugin[], Spec extends AnySpec> {
+  /** Each required plugin's `{ state, call, emit }` handle, keyed by name. */
+  readonly deps: DepsRecord<Deps>;
+  /** Emit one of this plugin's own events. */
+  readonly emit: EmitFn<Spec>;
+}
+/** The context passed to a plugin's `.middleware` / `.handlers` / `.lifecycle` — {@link DepsCtx} plus this plugin's own `state`. */
+interface PluginCtx<Deps extends readonly AnyPlugin[], Spec extends AnySpec, State> extends DepsCtx<Deps, Spec> {
+  /** This plugin's own computed `state` service. */
+  readonly state: State;
+}
+/** The config for {@link plugin} — the type-defining half (no implementation). */
+interface PluginConfig<Name extends string, Spec extends AnySpec, State, Deps extends readonly AnyPlugin[]> {
+  /** Unique plugin name (and the key dependents reference it by). */
+  readonly name: Name;
+  /** The plugins this one depends on — available in `ctx.deps` and installed first. */
+  readonly requires?: Deps;
+  /** The frontend-safe API contract this plugin contributes. */
+  readonly spec: Spec;
+  /** Build this plugin's exported **state** service from its dependency context (computed once at install). */
+  readonly state?: (ctx: DepsCtx<Deps, Spec>) => State;
+}
+/** A partial handler bag for a spec — what a `.handlers((ctx) => …)` factory returns (multiple merge). */
+type PartialHandlers<Spec extends AnySpec> = { readonly [K in keyof Spec['endpoints'] & string]?: HandlerFor<Spec, Spec['endpoints'][K] & AnyEndpoint> };
+/** The ctx-aware impl a `.middleware(def, …)` factory must return for def `M`. */
+type MwImpl<M extends AnyMiddleware> = [AnyMiddleware] extends [M] ? AnyFn : ImplFor<M>;
+/** The prebuilt bound pair a `.middleware(bound)` accepts for def `M`. */
+type MwBound<M extends AnyMiddleware> = [AnyMiddleware] extends [M] ? {
+  readonly def: AnyMiddleware;
+  readonly impl: AnyFn;
+} : BoundMiddleware<M>;
+/**
+ * A plugin builder — the value {@link plugin} returns and the host installs. Chain
+ * `.middleware`/`.handlers`/`.lifecycle` (each ctx-aware, returning a new builder).
+ * `typeof builder` types out-of-line handlers/middleware.
+ *
+ * @typeParam Name  - the plugin's unique name.
+ * @typeParam Spec  - its API spec.
+ * @typeParam State - its exported state-service type.
+ * @typeParam Deps  - the plugins it requires.
+ */
+interface Plugin<Name extends string, Spec extends AnySpec, State, Deps extends readonly AnyPlugin[]> extends PluginShape<Name, Spec, State, Deps> {
+  /** Bind a middleware def to a ctx-aware impl factory (binds only this plugin's own new middleware). */
+  middleware<M extends AnyMiddleware>(def: M, impl: (ctx: PluginCtx<Deps, Spec, State>) => MwImpl<M>): this;
+  /** Bind a prebuilt `{ def, impl }` pair (e.g. a package binder like `bearerAuth.server`). */
+  middleware<M extends AnyMiddleware>(bound: MwBound<M>): this;
+  /** Add a (partial) handler bag built from `ctx` — multiple calls merge. */
+  handlers(factory: (ctx: PluginCtx<Deps, Spec, State>) => PartialHandlers<Spec>): this;
+  /** Set lifecycle hooks built from `ctx`. */
+  lifecycle(factory: (ctx: PluginCtx<Deps, Spec, State>) => Lifecycle): this;
+}
+/** The dependency context type for a plugin `P` — `{ deps, emit, state }`. */
+type CtxOf<P> = PluginCtx<DepsOf<P>, SpecOf<P>, StateOf<P>>;
+/**
+ * The handler-factory record for a plugin `P` — one entry per endpoint, each a
+ * `(ctx) => handler` closing over the plugin's context. Type out-of-line handlers with
+ * `PluginHandlers<typeof p>['name']`.
+ */
+type PluginHandlers<P> = { readonly [K in keyof SpecOf<P>['endpoints'] & string]: (ctx: CtxOf<P>) => HandlerFor<SpecOf<P>, SpecOf<P>['endpoints'][K] & AnyEndpoint> };
+/** A single plugin handler factory — `PluginHandler<typeof p, 'addNote'>`. */
+type PluginHandler<P, K extends string> = K extends keyof PluginHandlers<P> ? PluginHandlers<P>[K] : never;
+/**
+ * A middleware-impl factory for a plugin `P` and middleware def `M` — a
+ * `(ctx) => ImplFor<M>` closing over the plugin's context. Type out-of-line middleware
+ * impls with `PluginMiddleware<typeof p, typeof mw>`.
+ */
+type PluginMiddleware<P, M extends AnyMiddleware> = (ctx: CtxOf<P>) => ImplFor<M>;
+/** The erased runtime a plugin value carries — read by {@link createPluginHost | the host}. @internal */
+
+/**
+ * Create a plugin **builder** from its config. The builder is inert until a
+ * {@link createPluginHost | host} installs it — at which point its `state` is computed,
+ * its `lifecycle.up` runs, and its `spec` + handlers are mounted live. Chain
+ * `.middleware`/`.handlers`/`.lifecycle` to add the implementation.
+ *
+ * @typeParam Name  - inferred from `config.name`.
+ * @typeParam Spec  - inferred from `config.spec`.
+ * @typeParam State - inferred from `config.state`'s return (`undefined` if omitted).
+ * @typeParam Deps  - inferred from `config.requires`.
+ */
+declare function plugin<const Name extends string, Spec extends AnySpec, State = undefined, const Deps extends readonly AnyPlugin[] = readonly []>(config: PluginConfig<Name, Spec, State, Deps>): Plugin<Name, Spec, State, Deps>;
+//#endregion
+//#region src/host.d.ts
+/** Options for {@link createPluginHost}. */
+interface PluginHostOptions {
+  /**
+   * Observe an error thrown while **tearing a plugin down** — a `down`/`stop` lifecycle hook,
+   * or removing its routes. Teardown is best-effort: such an error is swallowed so it can't
+   * strand the plugin half-removed or abort `shutdown` of the others; this hook lets you notice.
+   * `phase` is `'down'`, `'stop'`, or `'remove'`. Off by default; it must not throw.
+   */
+  readonly onError?: (err: unknown, phase: 'down' | 'stop' | 'remove', plugin: string) => void;
+}
+/** Manages plugins installed into a running server — see {@link createPluginHost}. */
+interface PluginHost {
+  /** Install a plugin (its `requires` must already be installed). Builds its ctx/state, runs `up`, mounts it live. */
+  install(plugin: AnyPlugin): Promise<void>;
+  /** Uninstall a plugin by name — drains (`down`), removes its routes/events, then tears down (`stop`). Throws if a live dependent remains. */
+  uninstall(name: string): Promise<void>;
+  /** The names of currently-installed plugins, in install order. */
+  installed(): readonly string[];
+  /** Uninstall every plugin in dependency-safe order (dependents before their deps). */
+  shutdown(): Promise<void>;
+}
+/**
+ * Create a {@link PluginHost} over a running {@link Server} (which may start nearly
+ * empty — e.g. `server(spec({ endpoints: {} }), [])` — or carry a core spec).
+ *
+ * @example
+ * ```ts
+ * const app = server(spec({ endpoints: {} }), []);
+ * const host = createPluginHost(app);
+ * await host.install(auth);     // a base plugin
+ * await host.install(users);    // requires auth → installed after it
+ * // ... app.fetch(...) now serves both plugins' endpoints ...
+ * await host.shutdown();
+ * ```
+ */
+declare function createPluginHost(app: Server<AnySpec>, opts?: PluginHostOptions): PluginHost;
+//#endregion
+export { type AnyPlugin, type CtxOf, type DepHandle, type DepsCtx, type DepsRecord, type Lifecycle, type NameOf, type PartialHandlers, type Plugin, type PluginConfig, type PluginCtx, type PluginHandler, type PluginHandlers, type PluginHost, type PluginHostOptions, type PluginMiddleware, type PluginShape, type SpecOf, type StateOf, createPluginHost, plugin };

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+import { AnyEndpoint, AnyMiddleware, AnySpec, BoundMiddleware, EmitFn, HandlerFor, ImplFor, LocalClient, Server } from "@ayepi/core";
+
+//#region src/plugin.d.ts
+
+/** Loosest internal function type — replaces the banned `Function`. */
+type AnyFn = (...args: never[]) => unknown;
+/** Lifecycle hooks a plugin runs around install/uninstall, in dependency order. */
+interface Lifecycle {
+  /** Start work — runs after the plugin's deps are up, before its endpoints serve. */
+  readonly up?: () => void | Promise<void>;
+  /** Drain — the pre-stop phase (stop accepting work, finish in-flight). */
+  readonly down?: () => void | Promise<void>;
+  /** Teardown — the post-stop phase (close resources). */
+  readonly stop?: () => void | Promise<void>;
+}
+/**
+ * The methods-free structural base every plugin builder satisfies — what the `*Of` /
+ * `PluginHandlers` / `CtxOf` helpers match on. Keeping `AnyPlugin` to this shape (no
+ * chain methods) is essential: comparing full builders would expand `.middleware`'s
+ * `ImplFor<M>` into `ImplFor<AnyMiddleware>` and recurse infinitely.
+ */
+interface PluginShape<Name extends string, Spec extends AnySpec, State, Deps extends readonly AnyPlugin[]> {
+  readonly name: Name;
+  readonly spec: Spec;
+  readonly requires: Deps;
+  /** @internal phantom carrier of the state-service type. */
+  readonly __state?: State;
+}
+/** Any plugin, erased — the constraint for `requires` lists and the host registry. */
+type AnyPlugin = PluginShape<string, AnySpec, unknown, readonly AnyPlugin[]>;
+/** Extract a plugin's exported state-service type. */
+type StateOf<P> = P extends {
+  readonly __state?: infer S;
+} ? S : never;
+/** Extract a plugin's spec. */
+type SpecOf<P> = P extends {
+  readonly spec: infer Sp extends AnySpec;
+} ? Sp : never;
+/** Extract a plugin's name. */
+type NameOf<P> = P extends {
+  readonly name: infer N extends string;
+} ? N : never;
+/** Extract a plugin's `requires` tuple. */
+type DepsOf<P> = P extends {
+  readonly requires: infer D extends readonly AnyPlugin[];
+} ? D : never;
+/** The handle a plugin gets for one of its dependencies. */
+interface DepHandle<P extends AnyPlugin> {
+  /** The dependency's exported **state** service (its functions + data). */
+  readonly state: StateOf<P>;
+  /** Call one of the dependency's endpoints in-process, with just a data payload. */
+  readonly call: LocalClient<SpecOf<P>>['call'];
+  /** Emit one of the dependency's events. */
+  readonly emit: EmitFn<SpecOf<P>>;
+}
+/** The `deps` record on a plugin context — keyed by each required plugin's name. */
+type DepsRecord<Deps extends readonly AnyPlugin[]> = { readonly [P in Deps[number] as NameOf<P>]: DepHandle<P> };
+/** The context passed to a plugin's `state` builder — its dependencies + an `emit` for its own events. */
+interface DepsCtx<Deps extends readonly AnyPlugin[], Spec extends AnySpec> {
+  /** Each required plugin's `{ state, call, emit }` handle, keyed by name. */
+  readonly deps: DepsRecord<Deps>;
+  /** Emit one of this plugin's own events. */
+  readonly emit: EmitFn<Spec>;
+}
+/** The context passed to a plugin's `.middleware` / `.handlers` / `.lifecycle` — {@link DepsCtx} plus this plugin's own `state`. */
+interface PluginCtx<Deps extends readonly AnyPlugin[], Spec extends AnySpec, State> extends DepsCtx<Deps, Spec> {
+  /** This plugin's own computed `state` service. */
+  readonly state: State;
+}
+/** The config for {@link plugin} — the type-defining half (no implementation). */
+interface PluginConfig<Name extends string, Spec extends AnySpec, State, Deps extends readonly AnyPlugin[]> {
+  /** Unique plugin name (and the key dependents reference it by). */
+  readonly name: Name;
+  /** The plugins this one depends on — available in `ctx.deps` and installed first. */
+  readonly requires?: Deps;
+  /** The frontend-safe API contract this plugin contributes. */
+  readonly spec: Spec;
+  /** Build this plugin's exported **state** service from its dependency context (computed once at install). */
+  readonly state?: (ctx: DepsCtx<Deps, Spec>) => State;
+}
+/** A partial handler bag for a spec — what a `.handlers((ctx) => …)` factory returns (multiple merge). */
+type PartialHandlers<Spec extends AnySpec> = { readonly [K in keyof Spec['endpoints'] & string]?: HandlerFor<Spec, Spec['endpoints'][K] & AnyEndpoint> };
+/** The ctx-aware impl a `.middleware(def, …)` factory must return for def `M`. */
+type MwImpl<M extends AnyMiddleware> = [AnyMiddleware] extends [M] ? AnyFn : ImplFor<M>;
+/** The prebuilt bound pair a `.middleware(bound)` accepts for def `M`. */
+type MwBound<M extends AnyMiddleware> = [AnyMiddleware] extends [M] ? {
+  readonly def: AnyMiddleware;
+  readonly impl: AnyFn;
+} : BoundMiddleware<M>;
+/**
+ * A plugin builder — the value {@link plugin} returns and the host installs. Chain
+ * `.middleware`/`.handlers`/`.lifecycle` (each ctx-aware, returning a new builder).
+ * `typeof builder` types out-of-line handlers/middleware.
+ *
+ * @typeParam Name  - the plugin's unique name.
+ * @typeParam Spec  - its API spec.
+ * @typeParam State - its exported state-service type.
+ * @typeParam Deps  - the plugins it requires.
+ */
+interface Plugin<Name extends string, Spec extends AnySpec, State, Deps extends readonly AnyPlugin[]> extends PluginShape<Name, Spec, State, Deps> {
+  /** Bind a middleware def to a ctx-aware impl factory (binds only this plugin's own new middleware). */
+  middleware<M extends AnyMiddleware>(def: M, impl: (ctx: PluginCtx<Deps, Spec, State>) => MwImpl<M>): this;
+  /** Bind a prebuilt `{ def, impl }` pair (e.g. a package binder like `bearerAuth.server`). */
+  middleware<M extends AnyMiddleware>(bound: MwBound<M>): this;
+  /** Add a (partial) handler bag built from `ctx` — multiple calls merge. */
+  handlers(factory: (ctx: PluginCtx<Deps, Spec, State>) => PartialHandlers<Spec>): this;
+  /** Set lifecycle hooks built from `ctx`. */
+  lifecycle(factory: (ctx: PluginCtx<Deps, Spec, State>) => Lifecycle): this;
+}
+/** The dependency context type for a plugin `P` — `{ deps, emit, state }`. */
+type CtxOf<P> = PluginCtx<DepsOf<P>, SpecOf<P>, StateOf<P>>;
+/**
+ * The handler-factory record for a plugin `P` — one entry per endpoint, each a
+ * `(ctx) => handler` closing over the plugin's context. Type out-of-line handlers with
+ * `PluginHandlers<typeof p>['name']`.
+ */
+type PluginHandlers<P> = { readonly [K in keyof SpecOf<P>['endpoints'] & string]: (ctx: CtxOf<P>) => HandlerFor<SpecOf<P>, SpecOf<P>['endpoints'][K] & AnyEndpoint> };
+/** A single plugin handler factory — `PluginHandler<typeof p, 'addNote'>`. */
+type PluginHandler<P, K extends string> = K extends keyof PluginHandlers<P> ? PluginHandlers<P>[K] : never;
+/**
+ * A middleware-impl factory for a plugin `P` and middleware def `M` — a
+ * `(ctx) => ImplFor<M>` closing over the plugin's context. Type out-of-line middleware
+ * impls with `PluginMiddleware<typeof p, typeof mw>`.
+ */
+type PluginMiddleware<P, M extends AnyMiddleware> = (ctx: CtxOf<P>) => ImplFor<M>;
+/** The erased runtime a plugin value carries — read by {@link createPluginHost | the host}. @internal */
+
+/**
+ * Create a plugin **builder** from its config. The builder is inert until a
+ * {@link createPluginHost | host} installs it — at which point its `state` is computed,
+ * its `lifecycle.up` runs, and its `spec` + handlers are mounted live. Chain
+ * `.middleware`/`.handlers`/`.lifecycle` to add the implementation.
+ *
+ * @typeParam Name  - inferred from `config.name`.
+ * @typeParam Spec  - inferred from `config.spec`.
+ * @typeParam State - inferred from `config.state`'s return (`undefined` if omitted).
+ * @typeParam Deps  - inferred from `config.requires`.
+ */
+declare function plugin<const Name extends string, Spec extends AnySpec, State = undefined, const Deps extends readonly AnyPlugin[] = readonly []>(config: PluginConfig<Name, Spec, State, Deps>): Plugin<Name, Spec, State, Deps>;
+//#endregion
+//#region src/host.d.ts
+/** Options for {@link createPluginHost}. */
+interface PluginHostOptions {
+  /**
+   * Observe an error thrown while **tearing a plugin down** — a `down`/`stop` lifecycle hook,
+   * or removing its routes. Teardown is best-effort: such an error is swallowed so it can't
+   * strand the plugin half-removed or abort `shutdown` of the others; this hook lets you notice.
+   * `phase` is `'down'`, `'stop'`, or `'remove'`. Off by default; it must not throw.
+   */
+  readonly onError?: (err: unknown, phase: 'down' | 'stop' | 'remove', plugin: string) => void;
+}
+/** Manages plugins installed into a running server — see {@link createPluginHost}. */
+interface PluginHost {
+  /** Install a plugin (its `requires` must already be installed). Builds its ctx/state, runs `up`, mounts it live. */
+  install(plugin: AnyPlugin): Promise<void>;
+  /** Uninstall a plugin by name — drains (`down`), removes its routes/events, then tears down (`stop`). Throws if a live dependent remains. */
+  uninstall(name: string): Promise<void>;
+  /** The names of currently-installed plugins, in install order. */
+  installed(): readonly string[];
+  /** Uninstall every plugin in dependency-safe order (dependents before their deps). */
+  shutdown(): Promise<void>;
+}
+/**
+ * Create a {@link PluginHost} over a running {@link Server} (which may start nearly
+ * empty — e.g. `server(spec({ endpoints: {} }), [])` — or carry a core spec).
+ *
+ * @example
+ * ```ts
+ * const app = server(spec({ endpoints: {} }), []);
+ * const host = createPluginHost(app);
+ * await host.install(auth);     // a base plugin
+ * await host.install(users);    // requires auth → installed after it
+ * // ... app.fetch(...) now serves both plugins' endpoints ...
+ * await host.shutdown();
+ * ```
+ */
+declare function createPluginHost(app: Server<AnySpec>, opts?: PluginHostOptions): PluginHost;
+//#endregion
+export { type AnyPlugin, type CtxOf, type DepHandle, type DepsCtx, type DepsRecord, type Lifecycle, type NameOf, type PartialHandlers, type Plugin, type PluginConfig, type PluginCtx, type PluginHandler, type PluginHandlers, type PluginHost, type PluginHostOptions, type PluginMiddleware, type PluginShape, type SpecOf, type StateOf, createPluginHost, plugin };

package/dist/index.js

@@ -0,0 +1,165 @@
+import { implement, localClient } from "@ayepi/core";
+//#region src/plugin.ts
+/** Build an immutable builder over the given state. */
+function makeBuilder(s) {
+	return {
+		name: s.name,
+		spec: s.spec,
+		requires: s.requires,
+		middleware(defOrBound, impl) {
+			const entry = impl ? {
+				def: defOrBound,
+				implFactory: impl
+			} : { bound: defOrBound };
+			return makeBuilder({
+				...s,
+				mws: [...s.mws, entry]
+			});
+		},
+		handlers(factory) {
+			return makeBuilder({
+				...s,
+				handlerFactories: [...s.handlerFactories, factory]
+			});
+		},
+		lifecycle(factory) {
+			return makeBuilder({
+				...s,
+				lifecycleFactory: factory
+			});
+		},
+		__state: (ctx) => s.stateFactory ? s.stateFactory(ctx) : void 0,
+		__implement: (ctx) => {
+			let b = implement(s.spec);
+			for (const mw of s.mws) b = mw.bound ? b.middleware(mw.bound) : b.middleware(mw.def, mw.implFactory(ctx));
+			const bag = {};
+			for (const hf of s.handlerFactories) Object.assign(bag, hf(ctx));
+			return b.handlers(bag);
+		},
+		__lifecycle: (ctx) => s.lifecycleFactory ? s.lifecycleFactory(ctx) : {}
+	};
+}
+/**
+* Create a plugin **builder** from its config. The builder is inert until a
+* {@link createPluginHost | host} installs it — at which point its `state` is computed,
+* its `lifecycle.up` runs, and its `spec` + handlers are mounted live. Chain
+* `.middleware`/`.handlers`/`.lifecycle` to add the implementation.
+*
+* @typeParam Name  - inferred from `config.name`.
+* @typeParam Spec  - inferred from `config.spec`.
+* @typeParam State - inferred from `config.state`'s return (`undefined` if omitted).
+* @typeParam Deps  - inferred from `config.requires`.
+*/
+function plugin(config) {
+	return makeBuilder({
+		name: config.name,
+		spec: config.spec,
+		requires: config.requires ?? [],
+		stateFactory: config.state,
+		mws: [],
+		handlerFactories: []
+	});
+}
+//#endregion
+//#region src/host.ts
+/**
+* Create a {@link PluginHost} over a running {@link Server} (which may start nearly
+* empty — e.g. `server(spec({ endpoints: {} }), [])` — or carry a core spec).
+*
+* @example
+* ```ts
+* const app = server(spec({ endpoints: {} }), []);
+* const host = createPluginHost(app);
+* await host.install(auth);     // a base plugin
+* await host.install(users);    // requires auth → installed after it
+* // ... app.fetch(...) now serves both plugins' endpoints ...
+* await host.shutdown();
+* ```
+*/
+function createPluginHost(app, opts = {}) {
+	const registry = /* @__PURE__ */ new Map();
+	const installSpec = app.install;
+	/** Report a swallowed teardown error (best-effort — a throwing `onError` is itself ignored). */
+	const report = (err, phase, plugin) => {
+		try {
+			opts.onError?.(err, phase, plugin);
+		} catch {}
+	};
+	/** Run a lifecycle hook so its failure is isolated — reported, not thrown — so teardown of the rest continues. */
+	const safe = async (hook, phase, plugin) => {
+		try {
+			await hook?.();
+		} catch (err) {
+			report(err, phase, plugin);
+		}
+	};
+	const liveDependents = (name) => [...registry.values()].filter((e) => e.plugin.requires.some((d) => d.name === name)).map((e) => e.plugin.name);
+	/** Assemble the `{ deps, emit }` base context for a plugin from the registry. */
+	function buildBaseCtx(plugin) {
+		const deps = {};
+		for (const dep of plugin.requires) {
+			const entry = registry.get(dep.name);
+			deps[dep.name] = {
+				state: entry.state,
+				call: localClient(app, dep.spec).call,
+				emit: app.emit
+			};
+		}
+		return {
+			deps,
+			emit: app.emit
+		};
+	}
+	async function install(plugin) {
+		if (registry.has(plugin.name)) throw new Error(`plugin "${plugin.name}" is already installed`);
+		for (const dep of plugin.requires) if (!registry.has(dep.name)) throw new Error(`plugin "${plugin.name}" requires "${dep.name}", which is not installed`);
+		const base = buildBaseCtx(plugin);
+		const internals = plugin;
+		const state = internals.__state(base);
+		const ctx = {
+			...base,
+			state
+		};
+		const builder = internals.__implement(ctx);
+		const lc = internals.__lifecycle(ctx);
+		await lc.up?.();
+		let handle;
+		try {
+			handle = installSpec(plugin.spec, [builder]);
+		} catch (err) {
+			await safe(() => lc.stop?.(), "stop", plugin.name);
+			throw err;
+		}
+		registry.set(plugin.name, {
+			plugin,
+			state,
+			lc,
+			handle
+		});
+	}
+	async function uninstall(name) {
+		const entry = registry.get(name);
+		if (!entry) throw new Error(`plugin "${name}" is not installed`);
+		const dependents = liveDependents(name);
+		if (dependents.length > 0) throw new Error(`cannot uninstall "${name}": still required by ${dependents.map((d) => `"${d}"`).join(", ")}`);
+		await safe(() => entry.lc.down?.(), "down", name);
+		try {
+			app.uninstall(entry.handle);
+		} catch (err) {
+			report(err, "remove", name);
+		}
+		await safe(() => entry.lc.stop?.(), "stop", name);
+		registry.delete(name);
+	}
+	async function shutdown() {
+		while (registry.size > 0) await uninstall([...registry.keys()].find((n) => liveDependents(n).length === 0));
+	}
+	return {
+		install,
+		uninstall,
+		installed: () => [...registry.keys()],
+		shutdown
+	};
+}
+//#endregion
+export { createPluginHost, plugin };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@ayepi/plugin",
+  "version": "0.1.0",
+  "description": "A plugin system for @ayepi/core — compose an API from independent plugins (spec + implementation + state service + lifecycle + deps) and install/uninstall them into a running server",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/plugin"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/plugin#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@ayepi/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "publint": "^0.3.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8",
+    "zod": "^4.4.3",
+    "@ayepi/core": "0.1.0"
+  },
+  "keywords": [
+    "ayepi",
+    "plugin",
+    "modular",
+    "plugins",
+    "lifecycle",
+    "dependency-injection",
+    "hot-reload"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "publint": "publint"
+  }
+}