every-plugin 2.9.1 → 2.9.3

package/skills/plugin-development/SKILL.md

@@ -109,7 +109,7 @@ export default createPlugin({
   }),
   contract,
 
-  initialize: (config) =>
+  initialize: (config, _plugins, tools) =>
     Effect.gen(function* () {
       const service = new MyService(config.variables.baseUrl, config.secrets.apiKey);
       yield* service.ping();
@@ -118,8 +118,8 @@ export default createPlugin({
 
   shutdown: () => Effect.void,
 
-  createRouter: (context, builder) => {
-    const { service } = context;
+  createRouter: (deps, builder) => {
+    const { service } = deps;
 
     const requireAuth = builder.middleware(async ({ context, next }) => {
       if (!context.userId) throw new ORPCError("UNAUTHORIZED", { message: "Auth required" });
@@ -148,12 +148,12 @@ import type { PluginsClient } from "./lib/plugins-types.gen";
 export default createPlugin.withPlugins<PluginsClient>()({
   variables: z.object({ demoMessage: z.string().optional() }),
   contract,
-  initialize: (config, plugins) =>
+  initialize: (config, plugins, _tools) =>
     Effect.sync(() => ({ plugins, demoMessage: config.variables.demoMessage ?? "not configured" })),
-  createRouter: (services, builder) => ({
+  createRouter: (deps, builder) => ({
     pluginDemo: builder.pluginDemo.handler(async () => {
-      const status = await services.plugins.registry().getRegistryStatus();
-      return { apiVariable: services.demoMessage, registryStatus: status };
+      const status = await deps.plugins.registry().getRegistryStatus();
+      return { apiVariable: deps.demoMessage, registryStatus: status };
     }),
   }),
 });
@@ -163,6 +163,51 @@ export default createPlugin.withPlugins<PluginsClient>()({
 - Call `services.plugins.{key}()` to execute plugin routers in-process — no HTTP roundtrip
 - The host loads non-API plugins first (Phase 1), then loads the API with `pluginsClient` injected (Phase 2)
 
+## Long-Lived Scoped Resources
+
+For database pools, caches, publisher channels, or any resource that should live for the plugin's lifetime, use `tools.buildService(tag, layer)` inside `initialize`:
+
+```typescript
+import { createPlugin } from "every-plugin";
+import { Effect, Layer } from "every-plugin/effect";
+
+export default createPlugin({
+  // ...
+  initialize: (config, _plugins, tools) =>
+    Effect.gen(function* () {
+      const repo = yield* tools.buildService(
+        MyRepoTag,
+        MyRepoLive.pipe(Layer.provide(DatabaseLive(config.secrets.MY_DATABASE_URL))),
+      );
+
+      const publisher = new MemoryPublisher({ resumeRetentionSeconds: 120 });
+
+      return { repo, publisher };
+    }),
+  // ...
+});
+```
+
+`tools.buildService(tag, layer)` binds the layer's resources to the plugin's lifecycle scope.
+Resources persist until the plugin shuts down and are automatically cleaned up during `runtime.shutdown()`.
+
+**Bad — creates a transient scope that closes immediately:**
+```typescript
+const svc = yield* Effect.provide(MyTag, MyLive.pipe(Layer.provide(DatabaseLive(url))))
+```
+
+**Good — resources persist for the plugin's lifetime:**
+```typescript
+const svc = yield* tools.buildService(MyTag, MyLive.pipe(Layer.provide(DatabaseLive(url))))
+```
+
+Key rules:
+- Use `tools.buildService(...)` for any `Layer.scoped(...)` resource that should survive initialization
+- Plain class construction (new Service(...)) is still fine directly in `initialize`
+- `createRouter(deps)` receives whatever `initialize` returns — same mental model as before
+- Do not use `Effect.provide(Tag, Layer.scoped(...))` for persistent dependencies inside `initialize`
+- `tools` is provided by the framework and does not need to be imported
+
 ## Dev Server Config (plugin.dev.ts)
 
 ```typescript
@@ -214,3 +259,4 @@ export default {
 - Forgetting `.errors(Errors)` on routes that can throw ORPCError — untyped errors
 - Using `Effect.runPromise` inside `Effect.gen` — use `yield*` instead for proper error channel
 - Putting business logic in `createRouter` — keep it in the service class, router is just glue
+- Using `Effect.provide(Tag, Layer.scoped(...))` inside `initialize` for long-lived resources — creates a transient scope that releases the resource immediately after initialization. Use `tools.buildService(Tag, Layer.scoped(...))` instead

package/skills/plugin-testing/SKILL.md

@@ -124,6 +124,61 @@ describe("API with mock registry", () => {
 });
 ```
 
+## Testing Scope Lifecycle
+
+When a plugin uses `tools.buildService(...)` inside `initialize`, verify that scoped resources persist after initialization and are released during shutdown:
+
+```typescript
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createPlugin, createPluginRuntime } from "every-plugin";
+import { Context, Effect, Layer } from "every-plugin/effect";
+
+let released = false;
+
+class TestTag extends Context.Tag("TestTag")<TestTag, { value: string }>() {}
+
+describe("scope lifecycle", () => {
+  let runtime: ReturnType<typeof createPluginRuntime>;
+
+  beforeAll(async () => {
+    const plugin = createPlugin({
+      // ... variables, secrets, contract ...
+      initialize: (_config, _plugins, tools) =>
+        Effect.gen(function* () {
+          const svc = yield* tools.buildService(TestTag, TestLive);
+          return { svc };
+        }),
+      createRouter: (deps) => ({
+        // ... routes ...
+      }),
+    });
+
+    runtime = createPluginRuntime({
+      registry: { "lifecycle-test": { module: plugin } },
+    });
+
+    await runtime.usePlugin("lifecycle-test", {
+      variables: {}, secrets: {},
+    });
+  });
+
+  it("resource persists after initialization", () => {
+    expect(released).toBe(false);
+  });
+
+  afterAll(async () => {
+    await runtime.shutdown();
+    expect(released).toBe(true);
+  });
+});
+```
+
+Key assertions:
+- Resource should NOT be released after `usePlugin()` completes
+- Resource SHOULD be released after `runtime.shutdown()`
+- Multiple independent plugins have independent scope lifetimes
+- `runtime.shutdown()` calls cleanup for all registered plugins
+
 ## Testing Streaming (eventIterator)
 
 Use `for await` to collect streaming results:

package/src/plugin.ts

@@ -1,8 +1,8 @@
 import type { AnyContractRouter, AnySchema, InferSchemaOutput } from "@orpc/contract";
 import { ORPCError } from "@orpc/contract";
-import type { Context, Implementer, Router } from "@orpc/server";
+import type { Implementer, Router } from "@orpc/server";
 import { implement, onError } from "@orpc/server";
-import { Effect, type Scope } from "effect";
+import { Effect, type Context as EffectContext, type Layer, type Scope } from "effect";
 import { extractFromFiberFailure, formatORPCError } from "./runtime/errors";
 
 type ContextOutput<T> = T extends AnySchema ? InferSchemaOutput<T> : Record<string, never>;
@@ -22,21 +22,36 @@ type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
   secrets: InferSchemaOutput<S>;
 };
 
+/**
+ * Tools provided to plugin initialize/services for building long-lived scoped resources.
+ */
+type ServiceOf<T> = T extends EffectContext.Tag<any, infer S> ? S : never;
+
+export type PluginServicesTools = {
+  buildService: <T>(tag: T, layer: Layer.Layer<any, any, any>) => Effect.Effect<ServiceOf<T>>;
+};
+
 type PluginDefinition<
   V extends AnySchema,
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Context,
+  TDeps extends Record<string, any>,
   P extends Record<string, unknown>,
 > = {
   variables: V;
   secrets: S;
   contract: TContract;
   context?: TRequestContext;
+  /**
+   * Initialize the plugin and build dependencies.
+   * A third argument `tools` is provided for building long-lived scoped resources
+   * (e.g. database pools) via `tools.buildService(tag, layer)`.
+   */
   initialize?: (
     config: PluginInitializeInput<V, S>,
     plugins: P,
+    tools: PluginServicesTools,
   ) => Effect.Effect<TDeps, Error, Scope.Scope>;
   createRouter: (
     deps: TDeps,
@@ -53,7 +68,7 @@ export interface LoadedPluginWithBinding<
   TVariables extends AnySchema,
   TSecrets extends AnySchema,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Context = Record<never, never>,
+  TDeps extends Record<string, any> = Record<never, never>,
 > {
   new (): Plugin<TContract, TVariables, TSecrets, TRequestContext, TDeps>;
   binding: {
@@ -72,7 +87,7 @@ export interface Plugin<
   TVariables extends AnySchema,
   TSecrets extends AnySchema,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Context = Record<never, never>,
+  TDeps extends Record<string, any> = Record<never, never>,
 > {
   readonly id: string;
   readonly contract: TContract;
@@ -81,6 +96,7 @@ export interface Plugin<
   initialize(
     config: PluginInitializeInput<TVariables, TSecrets>,
     plugins: Record<string, unknown>,
+    tools: PluginServicesTools,
   ): Effect.Effect<TDeps, unknown, Scope.Scope>;
 
   shutdown(): Effect.Effect<void, never>;
@@ -100,7 +116,7 @@ export interface CreatePluginFn {
     S extends AnySchema,
     TContract extends AnyContractRouter,
     TRequestContext extends AnySchema | undefined = undefined,
-    TDeps extends Context = Record<never, never>,
+    TDeps extends Record<string, any> = Record<never, never>,
     P extends Record<string, unknown> = Record<string, never>,
   >(
     config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
@@ -114,7 +130,7 @@ export const createPlugin: CreatePluginFn = function createPlugin<
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined = undefined,
-  TDeps extends Context = Record<never, never>,
+  TDeps extends Record<string, any> = Record<never, never>,
   P extends Record<string, unknown> = Record<string, never>,
 >(config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>) {
   const configSchema: PluginConfigFor<V, S, TRequestContext> = {
@@ -134,10 +150,11 @@ export const createPlugin: CreatePluginFn = function createPlugin<
     initialize(
       pluginConfig: PluginInitializeInput<V, S>,
       plugins: Record<string, unknown> = {},
+      tools: PluginServicesTools,
     ): Effect.Effect<TDeps, unknown, Scope.Scope> {
       const init = config.initialize ?? (() => Effect.succeed({} as TDeps));
 
-      return init(pluginConfig, plugins as P).pipe(
+      return init(pluginConfig, plugins as P, tools).pipe(
         Effect.tap((deps) =>
           Effect.sync(() => {
             this._deps = deps;
@@ -209,7 +226,7 @@ export type CreatePluginWithPlugins<P extends Record<string, unknown>> = <
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined = undefined,
-  TDeps extends Context = Record<never, never>,
+  TDeps extends Record<string, any> = Record<never, never>,
 >(
   config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
 ) => LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
@@ -220,7 +237,7 @@ export function withPlugins<P extends Record<string, unknown>>(): CreatePluginWi
     S extends AnySchema,
     TContract extends AnyContractRouter,
     TRequestContext extends AnySchema | undefined = undefined,
-    TDeps extends Context = Record<never, never>,
+    TDeps extends Record<string, any> = Record<never, never>,
   >(
     config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
   ) => createPlugin<V, S, TContract, TRequestContext, TDeps, P>(config as any);

package/src/runtime/errors.ts

@@ -132,7 +132,10 @@ export const formatORPCError = (error: any): string | null => {
   const message = error.message || "An error occurred";
 
   lines.push(`\n╭─ oRPC Error ${"─".repeat(40)}`);
-  lines.push(`│  ${message}`);
+  const messageLines = message.split("\n");
+  for (const line of messageLines) {
+    lines.push(`│  ${line}`);
+  }
   lines.push(`│  Code: ${code} (${status})`);
   lines.push(`│`);
 

package/src/runtime/index.ts

@@ -78,10 +78,11 @@ export class PluginRuntime<R = RegisteredPlugins> {
         const pluginService = yield* PluginService;
         const validatedId = yield* this.validatePluginId(pluginId);
 
-        // Load → Instantiate → Initialize
+        // Load → Instantiate → Initialize → Register
         const ctor = yield* pluginService.loadPlugin(validatedId);
         const instance = yield* pluginService.instantiatePlugin(pluginId, ctor);
         const initialized = yield* pluginService.initializePlugin(instance, config, plugins);
+        yield* pluginService.registerPlugin(initialized);
 
         return initialized;
       }).pipe(Effect.annotateLogs({ plugin: pluginId }), Effect.provide(this.runtime));
@@ -134,7 +135,9 @@ export class PluginRuntime<R = RegisteredPlugins> {
   ): Promise<InitializedPlugin<T>> {
     const effect = Effect.gen(function* () {
       const pluginService = yield* PluginService;
-      return yield* pluginService.initializePlugin(instance, config, plugins);
+      const initialized = yield* pluginService.initializePlugin(instance, config, plugins);
+      yield* pluginService.registerPlugin(initialized);
+      return initialized;
     }).pipe(Effect.annotateLogs({ plugin: instance.plugin.id }));
     return this.runPromise(effect);
   }
@@ -151,8 +154,9 @@ export class PluginRuntime<R = RegisteredPlugins> {
   async evictPlugin<K extends keyof R & string>(
     pluginId: K,
     config: PluginConfigInput<R[K]>,
+    plugins?: Record<string, unknown>,
   ): Promise<void> {
-    const cacheKey = this.generateCacheKey(pluginId, config);
+    const cacheKey = this.generateCacheKey(pluginId, { ...config, __plugins: plugins ?? {} });
 
     const effect = Effect.gen(this, function* () {
       const pluginService = yield* PluginService;

package/src/runtime/services/plugin-lifecycle.service.ts

@@ -49,6 +49,11 @@ export class PluginLifecycleService extends Effect.Service<PluginLifecycleServic
         cleanup: () =>
           Effect.gen(function* () {
             const plugins = yield* Ref.get(activePlugins);
+            if (typeof process !== "undefined" && process.env?.EVERY_PLUGIN_DEBUG_SCOPES === "1") {
+              yield* Effect.logWarning(
+                `[PluginLifecycle] cleaning up ${plugins.size} active plugin(s)`,
+              );
+            }
 
             yield* Effect.forEach(
               plugins,

package/src/runtime/services/plugin-loader.service.ts

@@ -1,6 +1,7 @@
 import type { InferSchemaInput, InferSchemaOutput } from "@orpc/contract";
-import { Context, Effect, Scope } from "effect";
+import { Context, Effect, Context as EffectContext, Layer, Scope } from "effect";
 import type { z } from "zod";
+import type { PluginServicesTools } from "../../plugin";
 import type {
   AnyPlugin,
   AnyPluginConstructor,
@@ -237,9 +238,28 @@ export class PluginLoaderService extends Effect.Service<PluginLoaderService>()(
             // Create a long-lived scope for this plugin instance
             const scope = yield* Scope.make();
 
+            // Create a per-plugin MemoMap so tool-built layers are memoized
+            const memoMap = yield* Layer.makeMemoMap;
+
+            const tools: PluginServicesTools = {
+              buildService: (tag: any, layer: any) =>
+                (Layer.buildWithMemoMap(layer, memoMap, scope) as any).pipe(
+                  Effect.map((ctx: any) => EffectContext.get(ctx, tag)) as any,
+                ),
+            };
+
             // Initialize plugin within the scope
+            // The plugin's initialize method handles:
+            //   1. Building services (DB pools, caches) via tools.buildService
+            //   2. Shaping final deps via initialize
+            // Any Layer.scoped resources built through tools.buildService are
+            // bound to the plugin scope and persist until the plugin is shutdown.
             const context = yield* plugin
-              .initialize({ variables: _variables, secrets: hydratedConfig.secrets }, plugins ?? {})
+              .initialize(
+                { variables: _variables, secrets: hydratedConfig.secrets },
+                plugins ?? {},
+                tools,
+              )
               .pipe(
                 Effect.provideService(Scope.Scope, scope),
                 Effect.tapError((_error) =>

package/src/runtime/services/plugin.service.ts

@@ -25,6 +25,7 @@ export class PluginService extends Effect.Service<PluginService>()("PluginServic
       loadPlugin: loader.loadPlugin,
       instantiatePlugin: loader.instantiatePlugin,
       initializePlugin: loader.initializePlugin,
+      registerPlugin: (plugin: InitializedPlugin<AnyPlugin>) => lifecycle.register(plugin),
       shutdownPlugin: (plugin: InitializedPlugin<AnyPlugin>) =>
         Effect.gen(function* () {
           yield* plugin.plugin